Organizing AI Projects

A well-organized project is easier to maintain, test, and scale. Here's how to structure AI projects professionally.

Basic Project Structure

my_ai_agent/
├── .env                  # API keys (never commit!)
├── .env.example          # Template for .env
├── .gitignore            # Files to exclude from git
├── requirements.txt      # Dependencies
├── README.md             # Project documentation
├── main.py               # Entry point
└── src/
    ├── __init__.py
    ├── agent.py          # Main agent logic
    ├── config.py         # Configuration
    └── tools/
        ├── __init__.py
        ├── search.py
        └── calculator.py

Configuration Module

# src/config.py
import os
from dotenv import load_dotenv

load_dotenv()

class Config:
    OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
    MODEL = os.getenv("MODEL", "gpt-4")
    TEMPERATURE = float(os.getenv("TEMPERATURE", "0.7"))
    MAX_TOKENS = int(os.getenv("MAX_TOKENS", "1000"))

    @classmethod
    def validate(cls):
        if not cls.OPENAI_API_KEY:
            raise ValueError("OPENAI_API_KEY not set")

# Validate on import
Config.validate()

Tools Package

# src/tools/__init__.py
from .search import SearchTool
from .calculator import CalculatorTool

__all__ = ["SearchTool", "CalculatorTool"]

# src/tools/search.py
class SearchTool:
    name = "web_search"
    description = "Search the web for information"

    def execute(self, query: str) -> str:
        # Implementation here
        return f"Results for: {query}"

Main Agent Module

# src/agent.py
from typing import List, Dict
from .config import Config
from .tools import SearchTool, CalculatorTool

class AIAgent:
    def __init__(self):
        self.model = Config.MODEL
        self.tools = [SearchTool(), CalculatorTool()]
        self.history: List[Dict] = []

    def chat(self, message: str) -> str:
        self.history.append({"role": "user", "content": message})
        # Agent logic here
        response = "Hello!"
        self.history.append({"role": "assistant", "content": response})
        return response

Entry Point

# main.py
from src.agent import AIAgent

def main():
    agent = AIAgent()

    print("AI Agent Ready! Type 'quit' to exit.")
    while True:
        user_input = input("You: ")
        if user_input.lower() == 'quit':
            break
        response = agent.chat(user_input)
        print(f"Agent: {response}")

if __name__ == "__main__":
    main()

Essential Files

.gitignore

# Environment
.env
venv/
__pycache__/

# IDE
.vscode/
.idea/

# Output
*.log
output/

requirements.txt

openai>=1.0.0
python-dotenv>=1.0.0
requests>=2.31.0

.env.example

OPENAI_API_KEY=your-key-here
MODEL=gpt-4
TEMPERATURE=0.7

Next, we'll learn about file operations in Python. :::