AI Tutorial Generator

Production-ready AI agent that analyzes GitHub repositories and generates comprehensive step-by-step tutorials with working code examples.

🚀 Features

• Single-Agent System: Single LangGraph agent that uses 5 tools to orchestrate the entire workflow for repository discovery, analysis, and tutorial generation
• Async Processing: Background job processing with Celery + Redis
• Production Ready: Optimized for Render.com free tier (512MB RAM, 25MB storage)
• Cost Optimized: Uses Claude Haiku only, aggressive caching, sequential processing

📋 Prerequisites

• Python 3.11+
• Git
• Docker Desktop (for local development)
• GitHub account
• Render.com account (free)
• Anthropic API key
• GitHub Personal Access Token

Getting API Keys

Anthropic API Key:

1. Go to https://console.anthropic.com
2. Sign up/login
3. Navigate to "API Keys" in settings
4. Click "Create Key"
5. Copy key (starts with sk-ant-...)
6. Free tier: $5 credits included

GitHub Token:

1. GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click "Generate new token"
3. Select scopes: public_repo (read-only access to public repositories)
4. Copy token
5. Store securely (won't be shown again)

🛠️ Local Development

Step 1: Clone Repository

git clone <your-repo-url>
cd git_agent

Step 2: Install uv

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to PATH (add to ~/.bashrc or ~/.zshrc for persistence)
export PATH="$HOME/.cargo/bin:$PATH"

Step 3: Create Virtual Environment and Install Dependencies

# Create virtual environment and install dependencies using uv sync
# This reads from pyproject.toml and automatically creates .venv
uv sync

# Activate virtual environment (uv sync creates it automatically)
# macOS/Linux:
source .venv/bin/activate

# Windows:
.venv\Scripts\activate

Note: uv sync automatically:

• Creates a virtual environment (.venv/)
• Installs all dependencies from pyproject.toml
• Locks versions for reproducibility

Adding new dependencies:

# Add a new dependency
uv add package-name

# Add a dev dependency
uv add --dev package-name

# This automatically updates pyproject.toml

Note: requirements.txt is kept for Docker compatibility. To regenerate it from pyproject.toml:

uv pip compile pyproject.toml -o requirements.txt

Step 4: Configure Environment

cp .env.example .env
# Edit .env with your API keys

Step 5: Start Services

# Start PostgreSQL and Redis
docker-compose up -d

# Initialize database
alembic upgrade head

# Start FastAPI server (Terminal 1)
uvicorn app.main:app --reload --port 8000

# Start Celery worker (Terminal 2)
celery -A app.celery_app worker --loglevel=info

Step 6: Test

curl http://localhost:8000/health

Expected response:

{
  "status": "healthy",
  "database": "connected",
  "redis": "connected",
  "worker": "active"
}

🚢 Deployment to Render.com

Pre-Deployment

1. Push code to GitHub
2. Have API keys ready
3. Ensure render.yaml is in repository

Deployment Steps

1. Create Render Account

   • Go to https://render.com
   • Sign up with GitHub
   • Authorize repository access

2. Deploy from Blueprint

   • Dashboard → "New +" → "Blueprint"
   • Connect GitHub repository
   • Render detects render.yaml automatically
   • Review services: Web Service, Worker, PostgreSQL, Redis
   • Click "Apply"

3. Configure Environment Variables

   For Web Service (tutorial-generator-api):

   • Service → "Environment" tab
   • Add: ANTHROPIC_API_KEY = your_key
   • Add: GITHUB_TOKEN = your_token
   • Click "Save Changes"

   For Worker Service (tutorial-generator-worker):

   • Repeat same environment variables

4. Monitor Deployment

   • Check "Events" tab for progress
   • Wait 5-10 minutes for initial build
   • Verify all 4 services show "Live" status

5. Verify Deployment

   curl https://your-app-name.onrender.com/health

Post-Deployment

• API Docs: https://your-app-name.onrender.com/docs
• Monitor logs in Render dashboard
• Set up database backups (optional)

📚 API Documentation

POST /api/v1/generate

Generate a tutorial for a technology.

Request:

curl -X POST https://your-app.onrender.com/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"technology": "FastAPI", "max_repos": 3}'

Response:

{
  "job_id": "abc123",
  "status": "queued",
  "message": "Tutorial generation started"
}

GET /api/v1/jobs/{job_id}

Get job status.

Response:

{
  "job_id": "abc123",
  "status": "processing",
  "progress": 45,
  "created_at": "2024-01-01T00:00:00Z"
}

GET /api/v1/jobs/{job_id}/result

Get completed tutorial.

Response:

{
  "job_id": "abc123",
  "status": "completed",
  "tutorial": {
    "title": "Complete FastAPI Tutorial",
    "sections": [...],
    "code_examples": [...]
  }
}

DELETE /api/v1/jobs/{job_id}

Cancel a running job.

GET /health

Health check endpoint.

💡 Usage Examples

Generate Tutorial:

curl -X POST http://localhost:8000/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"technology": "Redis"}'

Check Status:

curl http://localhost:8000/api/v1/jobs/{job_id}

Poll for Completion:

while true; do
  STATUS=$(curl -s http://localhost:8000/api/v1/jobs/{job_id} | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] && break
  sleep 10
done

🗑️ Taking Down Deployment

Option 1: Delete Everything (Permanent)

1. Stop Services:

   • Dashboard → Each service → "Suspend"

2. Delete Services (in order):

   • Web Service → Settings → "Delete Web Service" → Confirm
   • Worker → Settings → "Delete Background Worker" → Confirm
   • PostgreSQL → Settings → "Delete Database" → Type name → Confirm
   • Redis → Settings → "Delete Redis Instance" → Confirm

3. Verify:

   • Dashboard shows no services
   • Billing shows $0/month

Option 2: Suspend (Temporary)

• Dashboard → Service → "Suspend"
• Resume anytime with "Resume" button

Note: Free tier databases reset after 90 days of inactivity.

🔧 Troubleshooting

Deployment Issues

Service won't start:

• Check environment variables are set
• Review logs in Render dashboard
• Verify database connection string

Build failures:

• Check pyproject.toml syntax
• Verify Python version (3.11+)
• Review build logs for errors

Runtime Issues

Cold start delays:

• First request after 15min inactivity takes ~30s
• Normal for free tier (service auto-sleeps)

Out of memory:

• Reduce max_repos to 2
• Check for memory leaks in logs
• Restart service

Rate limit exceeded:

• Limit: 10 requests/hour per IP
• Wait before retrying
• Use rate limiting headers in response

Local Development

Docker not starting:

docker-compose down
docker-compose up -d

Database connection refused:

• Verify PostgreSQL is running: docker ps
• Check connection string in .env

Dependencies not installing:

• Make sure uv is in PATH: which uv
• Try: uv sync --reinstall

⚠️ Free Tier Limitations

• RAM: 512MB (strict limit)
• Storage: 25MB PostgreSQL, 25MB Redis
• Uptime: 750 hours/month
• Auto-sleep: After 15min inactivity (30s cold start)
• Database: Resets after 90 days inactivity
• Processing: Max 3 repos, 10min timeout, sequential only

💰 Cost Analysis

Free Tier (First Month):

• Render: $0
• Anthropic: $5 free credits (~20-50 tutorials)
• Total: FREE

After Free Credits:

• Render: $0
• Anthropic: ~$0.10 per tutorial
• 100 tutorials/month: ~$10

Paid Upgrade (Optional):

• Render Starter: $7/service
• Total: $21/month (API + Worker + DB)
• Benefits: No cold starts, more RAM, persistent DB

🏗️ Architecture

System Architecture

┌─────────────┐
│   FastAPI   │
│   (API)     │
└──────┬──────┘
       │
       ├──► Celery Worker ──► LangGraph Agent
       │                        └── Single Agent with 5 Tools
       │                            ├── search_github_repositories
       │                            ├── analyze_repository_structure
       │                            ├── get_repository_code_samples
       │                            ├── synthesize_patterns
       │                            └── calculate_quality_score
       │
       ├──► PostgreSQL (Jobs/Results)
       │
       └──► Redis (Cache/Queue)

AI Agent Architecture (Single Agent with Tools)

The tutorial generation is powered by a single LangGraph agent that uses 5 tools to orchestrate the entire workflow. This simpler architecture is more efficient and easier to maintain than a multi-agent system.

Agent Workflow

graph TD
    A[Start] --> B[Single Tutorial Agent]
    B --> C{Tool Call?}
    C -->|Yes| D[Execute Tool]
    C -->|No| E[Generate Content]
    D --> F[Update State]
    E --> F
    F --> G{Complete?}
    G -->|No| B
    G -->|Yes| H[End]
    
    style B fill:#e1f5ff
    style D fill:#fff4e1
    style E fill:#e8f5e9

Loading

Single Agent with Tools

Tutorial Agent - One LLM-powered agent that orchestrates the entire workflow:

• LLM: Claude Haiku (claude-3-haiku-20240307)
• Purpose: Decide which tools to use and generate tutorial content
• Process:
  • Receives state and decides next action
  • Calls appropriate tools when needed
  • Generates content using LLM when ready
  • Updates progress and state after each step

Tools Available to Agent

1. search_github_repositories(query, max_results) (Progress: 0-10%)

• Purpose: Search and rank GitHub repositories
• Process:
  • Searches GitHub using query: "{technology} production best practices"
  • Sorts by stars (most popular first)
  • Returns top N repositories (default: 3, max: 3)
  • Results cached for 1 hour in Redis
• Output: List of repository metadata (name, stars, description, URL)

2. analyze_repository_structure(repo_url) (Progress: 10-40%)

• Purpose: Analyze repository structure and extract metadata
• Process:
  • Extracts file structure (important files only)
  • Retrieves README content (first 5KB)
  • Extracts topics and metadata
  • Results cached per repository for 1 hour
• Output: Repository structure with files, topics, and README

3. get_repository_code_samples(repo_url, file_paths) (Progress: 10-40%)

• Purpose: Extract code samples from specific files
• Process:
  • Gets code from top 5 key files (max 10KB each)
  • Only retrieves files < 50KB
  • Results cached for 1 hour
• Output: Dictionary mapping file paths to code content

4. synthesize_patterns(analyzed_repos) (Progress: 40-60%)

• Purpose: Aggregate findings and extract common patterns
• Process:
  • Identifies common file structures across repositories
  • Extracts shared topics and themes
  • Compiles best practices from READMEs
  • Builds architecture overview
• Output: Patterns, best practices list, architecture notes

5. calculate_quality_score(tutorial_content, errors) (Progress: 90-100%)

• Purpose: Validate tutorial completeness and quality
• Process:
  • Calculates quality score (0-100):
    • Deducts points for errors
    • Checks section completeness
    • Validates content length
• Output: Quality score (0-100)

Content Generation

When the agent has collected all repository data, it uses the LLM directly (no tools) to:

• Generate comprehensive tutorial content
• Create sections: Introduction, Getting Started, Architecture Patterns, Best Practices, Code Examples, Deployment
• Incorporate code examples and best practices from analyzed repos
• Produce production-focused, practical content

State Management

All agents share a TypedDict state (AgentState) that includes:

{
    "technology": str,              # Input technology name
    "max_repos": int,               # Max repos to analyze
    "repositories": list[dict],     # Discovered repos
    "analyzed_repos": list[dict],   # Analyzed repo data
    "patterns": list[dict],         # Extracted patterns
    "best_practices": list[str],    # Best practices list
    "architecture": dict,           # Architecture overview
    "tutorial_structure": dict,     # Planned structure
    "tutorial_content": dict,       # Generated content
    "quality_score": float,         # Quality score (0-100)
    "errors": list[str],            # Error messages
    "progress": int,                # Progress (0-100)
    "current_step": str,            # Current agent step
}

Tools Available to Agents

GitHub API Tools:

• search_github_repositories(query, max_results) - Search GitHub repos
• analyze_repository_structure(repo_url) - Get repo structure and metadata
• get_repository_code_samples(repo_url, file_paths) - Extract code from files

Caching Strategy:

• All GitHub API calls cached in Redis (1 hour TTL)
• Reduces API rate limit issues
• Speeds up repeated requests
• Cache keys: github_search:{query}, repo_structure:{repo}, etc.

Optimization for Free Tier

Memory Optimization:

• ✅ Sequential processing (one repo at a time)
• ✅ Limits: 3 repos max, 5 files per repo, 10KB per file
• ✅ Aggressive caching to reduce API calls
• ✅ Progress tracking for monitoring

Cost Optimization:

• ✅ Claude Haiku only (cheapest model)
• ✅ Cached LLM responses where possible
• ✅ Limited token usage per section
• ✅ No parallel processing (saves memory)

Performance:

• ✅ Redis caching for all external API calls
• ✅ Database connection pooling (2 connections)
• ✅ Timeout: 10 minutes per job
• ✅ Progress updates to database

Execution Flow

1. User Request → FastAPI receives request
2. Job Creation → Job record created in PostgreSQL
3. Celery Task → Background task queued in Redis
4. LangGraph Execution → Single agent orchestrates workflow:
   • Agent decides which tool to call based on current state
   • Tools execute and return results
   • State updated after each tool execution
   • Agent generates content when all data collected
   • Progress tracked in database
   • Errors collected in state
5. Result Storage → Final tutorial stored in job.result (JSON)
6. User Retrieval → User polls for completion and retrieves result

Error Handling

• Agent and tools have try-except blocks
• Errors collected in state["errors"] list
• Job marked as failed if critical errors occur
• Partial results saved if possible
• Maximum 2 retries on transient failures

Why Single Agent?

Advantages:

• ✅ Simpler Architecture: One agent is easier to understand and maintain
• ✅ More Flexible: LLM can decide tool order dynamically
• ✅ Less Overhead: Fewer function calls and state transitions
• ✅ Better Tool Integration: Tools are first-class citizens, not separate agents
• ✅ Easier Debugging: Single point of control for the workflow

Trade-offs:

• Most steps are deterministic (tool calls), not agent decisions
• Only content generation truly needs LLM reasoning
• Simpler is better for this use case

📝 License

MIT License - see LICENSE file for details

🤝 Contributing

Contributions welcome! Please open an issue or submit a PR.