venv-docker-setup.md

Complete Setup Guide: PocketFlow Working Codebase Knowledge

📋 Prerequisites

Before starting, ensure you have:

• Python 3.8+ (for venv method)
• Docker (for Docker method)
• LLM API Key - Gemini API key (recommended) or other supported models
• GitHub Token (optional, for private repos or avoiding rate limits)

🐍 Method 1: Virtual Environment Setup

Step 1: Clone the Repository

git clone https://github.com/mhwebdevelopment/PocketFlow-Working-Codebase-Knowledge
cd PocketFlow-Working-Codebase-Knowledge

Step 2: Create and Activate Virtual Environment

On Windows:

# Create virtual environment
python -m venv pocketflow_env

# Activate it
pocketflow_env\Scripts\activate

On macOS/Linux:

# Create virtual environment
python3 -m venv pocketflow_env

# Activate it
source pocketflow_env/bin/activate

💡 Pro Tip: You'll see (pocketflow_env) in your terminal prompt when the virtual environment is active.

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Configure LLM Credentials

Edit the file utils/call_llm.py and set up your API credentials:

# For Gemini (recommended)
client = genai.Client(
    api_key=os.getenv("GEMINI_API_KEY", "your-actual-api-key-here")
)

Environment Variable Method (Recommended): Create a .env file in the project root:

# .env file
GEMINI_API_KEY=your_actual_api_key_here
GITHUB_TOKEN=your_github_token_here  # Optional

Step 5: Verify Setup

Test your LLM configuration:

python utils/call_llm.py

If successful, you should see a response from the LLM.

Step 6: Run Your First Analysis

Analyze a GitHub Repository:

python main.py --repo https://github.com/username/repo --include "*.py" "*.js" --exclude "tests/*" --max-size 50000

Analyze a Local Directory:

python main.py --dir /path/to/your/codebase --include "*.py" --exclude "*test*"

Step 7: Deactivate Environment (When Done)

deactivate

🐳 Method 2: Docker Setup

Docker provides a cleaner, isolated environment and handles all dependencies automatically.

Step 1: Clone the Repository

git clone https://github.com/mhwebdevelopment/PocketFlow-Working-Codebase-Knowledge
cd PocketFlow-Working-Codebase-Knowledge

Step 2: Build Docker Image

docker build -t pocketflow-app .

💡 Understanding the Build: This creates a containerized version of the application with all dependencies pre-installed.

Step 3: Run with Docker

For Public GitHub Repositories:

docker run -it --rm \
    -e GEMINI_API_KEY="your_actual_api_key_here" \
    -v "$(pwd)/output_tutorials":/app/output \
    pocketflow-app --repo https://github.com/username/repo

For Private Repositories (with GitHub Token):

docker run -it --rm \
    -e GEMINI_API_KEY="your_actual_api_key_here" \
    -e GITHUB_TOKEN="your_github_token_here" \
    -v "$(pwd)/output_tutorials":/app/output \
    pocketflow-app --repo https://github.com/username/private-repo

For Local Directory Analysis:

docker run -it --rm \
    -e GEMINI_API_KEY="your_actual_api_key_here" \
    -v "/path/to/your/local_codebase":/app/code_to_analyze \
    -v "$(pwd)/output_tutorials":/app/output \
    pocketflow-app --dir /app/code_to_analyze

🔍 Docker Flags Explained:

• -it: Interactive terminal
• --rm: Automatically remove container when it exits
• -e: Set environment variables
• -v: Mount volumes (link host directories to container)

🛠 Complete Command Reference

Core Parameters

Parameter	Description	Example
--repo	GitHub repository URL	--repo https://github.com/user/repo
--dir	Local directory path	--dir /path/to/code
-n, --name	Project name (optional)	--name "My Project"
-o, --output	Output directory	--output ./my_tutorials

Filtering Options

Parameter	Description	Example
-i, --include	File patterns to include	--include "*.py" "*.js"
-e, --exclude	File patterns to exclude	--exclude "tests/*" "docs/*"
-s, --max-size	Max file size in bytes	--max-size 50000

Advanced Options

Parameter	Description	Default
--language	Tutorial language	english
--max-abstractions	Max abstractions to identify	10
--no-cache	Disable LLM caching	false

🚀 Practical Examples

Example 1: Analyze FastAPI Repository

# Virtual Environment
python main.py --repo https://github.com/tiangolo/fastapi \
    --include "*.py" \
    --exclude "tests/*" "docs/*" \
    --max-size 100000 \
    --output ./fastapi_tutorial

# Docker
docker run -it --rm \
    -e GEMINI_API_KEY="your_key_here" \
    -v "$(pwd)/fastapi_tutorial":/app/output \
    pocketflow-app --repo https://github.com/tiangolo/fastapi \
    --include "*.py" --exclude "tests/*" "docs/*"

Example 2: Analyze Local React Project

# Virtual Environment
python main.py --dir ./my-react-app \
    --include "*.js" "*.jsx" "*.ts" "*.tsx" \
    --exclude "node_modules/*" "build/*" \
    --language "english"

# Docker
docker run -it --rm \
    -e GEMINI_API_KEY="your_key_here" \
    -v "./my-react-app":/app/code_to_analyze \
    -v "$(pwd)/react_tutorial":/app/output \
    pocketflow-app --dir /app/code_to_analyze \
    --include "*.js" "*.jsx" "*.ts" "*.tsx"

Example 3: Generate Tutorial in Different Language

python main.py --repo https://github.com/user/repo --language "Spanish"

🔧 Troubleshooting Guide

Common Issues and Solutions

1. LLM API Key Issues

# Error: API key not found
# Solution: Verify your API key in utils/call_llm.py or environment variables
export GEMINI_API_KEY="your_actual_key_here"
python utils/call_llm.py  # Test the connection

2. GitHub Rate Limiting

# Error: GitHub API rate limit exceeded
# Solution: Add GitHub token
export GITHUB_TOKEN="your_github_token_here"

3. Large Repository Processing

# Error: Repository too large
# Solution: Use filtering options
python main.py --repo https://github.com/large/repo \
    --include "*.py" \
    --exclude "tests/*" "vendor/*" "third_party/*" \
    --max-size 50000

4. Docker Volume Issues on Windows

# Use forward slashes and full paths
docker run -it --rm \
    -e GEMINI_API_KEY="your_key" \
    -v "C:/Users/YourName/output":/app/output \
    pocketflow-app --repo https://github.com/user/repo

5. Permission Errors (Linux/macOS)

# Fix output directory permissions
sudo chown -R $USER:$USER ./output_tutorials

📁 Understanding the Output

After running the analysis, you'll find:

output_tutorials/
├── tutorial.md              # Main tutorial document
├── abstractions/            # Core abstractions identified
├── interactions/            # How components interact
└── visualizations/          # Diagrams and flowcharts

🎯 Best Practices

For Virtual Environment Users

1. Always activate your environment before running commands
2. Keep requirements.txt updated if you add new dependencies
3. Use environment variables for sensitive API keys
4. Create separate environments for different projects

For Docker Users

1. Use volume mounts to persist output data
2. Set resource limits for large repository analysis:

   docker run --memory=4g --cpus=2 [other options]

3. Use Docker Compose for complex setups:

   # docker-compose.yml
   version: '3.8'
   services:
     pocketflow:
       build: .
       environment:
         - GEMINI_API_KEY=${GEMINI_API_KEY}
         - GITHUB_TOKEN=${GITHUB_TOKEN}
       volumes:
         - ./output:/app/output

Performance Optimization

1. Filter intelligently - exclude test files, documentation, and vendor code
2. Set reasonable file size limits - start with 50KB and adjust as needed
3. Use caching - don't use --no-cache unless necessary
4. Limit abstractions - start with default 10, increase only if needed

🚀 Next Steps

Once you have the tool running successfully:

1. Experiment with different repositories - try analyzing codebases you're learning
2. Customize the output language - generate working knowledge in your preferred language
3. Integrate into your workflow - use it for code reviews and onboarding
4. Contribute back - share interesting tutorials in the project's discussions

This setup gives you a powerful AI-assisted code analysis tool that can transform complex codebases into understandable working knowledge documentation. Whether you choose the virtual environment or Docker approach, you're now equipped to analyze and understand any codebase more effectively.

1