setup-guide.md

🚀 Development Setup Guide

This guide will help you set up the Audio Transcription Tool for local development.

Prerequisites

Required Software

• Python 3.8+: Download Python
• Git: Download Git
• OpenAI API Key: Get API Key

Recommended Tools

• UV Package Manager: Install UV (recommended)
• VS Code: Download VS Code with Python extension
• Terminal/Command Prompt: For running commands

Installation

1. Clone the Repository

git clone git@github.com:tomdwipo/agent.git
cd agent

2. Set Up Python Environment

Option A: Using UV (Recommended)

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

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv sync

Option B: Using pip

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

# Install dependencies
pip install -r requirements.txt

3. Environment Configuration

Create Environment File

# Copy example environment file
cp .env.example .env

# Edit the .env file with your settings

Configure Environment Variables

Edit .env file with your settings:

# Required for AI features
OPENAI_API_KEY=sk-your-openai-api-key-here

# Optional configurations
WHISPER_MODEL=base
OPENAI_MODEL=gpt-4
MAX_FILE_SIZE_MB=500
GRADIO_SERVER_PORT=7860
GRADIO_DEBUG=true

# Feature toggles
ENABLE_KEY_POINTS=true
ENABLE_PRD_GENERATION=true

# PRD Configuration
PRD_OPENAI_MODEL=gpt-4
PRD_MAX_TOKENS=2000
PRD_TEMPERATURE=0.3

4. Verify Installation

Check Python Environment

# Verify Python version
python --version

# Verify packages are installed
pip list | grep -E "(gradio|openai|whisper)"

Test Configuration

# Run configuration demo
python -m demos config

# Or run directly
python demos/config_demo.py

Test Services

# Run services demo
python -m demos services

# Test individual services
python demos/services_demo.py

5. Run the Application

Start Development Server

# Run the main application
python transcribe_gradio.py

# Or use UV
uv run transcribe_gradio.py

Access the Application

Open your browser and navigate to:

• Local: http://localhost:7860
• Network: http://0.0.0.0:7860 (if configured)

Development Environment Setup

IDE Configuration

VS Code Setup

1. Install Extensions:

   • Python
   • Python Docstring Generator
   • GitLens
   • Pylance

2. Configure Settings (.vscode/settings.json):

{
    "python.defaultInterpreterPath": ".venv/bin/python",
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true,
    "python.formatting.provider": "black",
    "python.sortImports.args": ["--profile", "black"],
    "editor.formatOnSave": true
}

3. Configure Launch (.vscode/launch.json):

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal"
        },
        {
            "name": "Run Main App",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/transcribe_gradio.py",
            "console": "integratedTerminal"
        }
    ]
}

Code Quality Tools

Install Development Tools

# Using UV
uv add --dev black pylint pytest pytest-cov

# Using pip
pip install black pylint pytest pytest-cov

Configure Code Formatting

# Format code with Black
black .

# Check code style
pylint services/ ui/ config/

Project Structure Overview

audio-transcription-tool/
├── transcribe_gradio.py          # Main application entry point
├── requirements.txt              # Python dependencies
├── pyproject.toml               # Project configuration
├── .env                         # Environment variables
│
├── services/                    # Business logic services
│   ├── whisper_service.py       # Audio transcription
│   ├── openai_service.py        # AI analysis and PRD generation
│   └── file_service.py          # File operations
│
├── config/                      # Configuration management
│   ├── settings.py              # Environment settings
│   └── constants.py             # Application constants
│
├── ui/                          # User interface components
│   ├── components.py            # Reusable UI components
│   └── gradio_interface.py      # Interface implementations
│
├── demos/                       # Demo scripts and examples
├── tests/                       # Test suite
└── docs/                        # Documentation

Common Development Tasks

Running Tests

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=services --cov=ui --cov=config

# Run specific test file
python -m pytest tests/test_prd_services.py

Running Demo Scripts

# List available demos
python -m demos list

# Run all demos
python -m demos all

# Run specific demo
python -m demos services
python -m demos ui
python -m demos config

Code Quality Checks

# Format code
black .

# Check linting
pylint services/ ui/ config/

# Type checking (if using mypy)
mypy services/ ui/ config/

Adding New Dependencies

Using UV

# Add runtime dependency
uv add package-name

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

# Update dependencies
uv sync

Using pip

# Install and add to requirements
pip install package-name
pip freeze > requirements.txt

Environment-Specific Setup

Development Environment

ENVIRONMENT=development
GRADIO_DEBUG=true
LOG_LEVEL=DEBUG
ENABLE_LOGGING=true

Production Environment

ENVIRONMENT=production
GRADIO_DEBUG=false
GRADIO_SHARE=false
LOG_LEVEL=INFO

Testing Environment

ENVIRONMENT=testing
WHISPER_MODEL=tiny
MAX_FILE_SIZE_MB=10

Troubleshooting

Common Issues

1. Import Errors

Problem: ModuleNotFoundError when importing services Solution:

# Ensure you're in the project root
pwd

# Activate virtual environment
source .venv/bin/activate  # or venv/bin/activate

# Reinstall dependencies
uv sync  # or pip install -r requirements.txt

2. OpenAI API Issues

Problem: OpenAI features not working Solution:

# Check API key configuration
python -c "from config.settings import settings; print(settings.is_openai_configured())"

# Test API connection
python demos/services_demo.py

3. Gradio Port Issues

Problem: Port 7860 already in use Solution:

# Use different port
GRADIO_SERVER_PORT=8080 python transcribe_gradio.py

# Or kill existing process
lsof -ti:7860 | xargs kill -9

4. Audio File Issues

Problem: Audio files not processing Solution:

# Check supported formats
python -c "from config.constants import SUPPORTED_AUDIO_FORMATS; print(SUPPORTED_AUDIO_FORMATS)"

# Test with small file
python demos/services_demo.py

Getting Help

1. Check Configuration:

   python demos/config_demo.py

2. Run Diagnostics:

   python demos/test_runner.py

3. Check Logs: Look for error messages in the terminal output

4. Review Documentation: Check the API documentation for detailed usage

Development Workflow

Daily Development

1. Start Development Session:

   cd /path/to/project
   source .venv/bin/activate
   git pull origin main

2. Make Changes: Edit code, add features, fix bugs

3. Test Changes:

   python -m pytest
   python demos/test_runner.py

4. Format and Lint:

   black .
   pylint services/ ui/ config/

5. Commit Changes:

   git add .
   git commit -m "Description of changes"
   git push origin feature-branch

Feature Development

1. Create Feature Branch:

   git checkout -b feature/new-feature

2. Implement Feature: Follow the architecture patterns

3. Add Tests: Write tests for new functionality

4. Update Documentation: Update relevant docs

5. Create Pull Request: Submit for review

Next Steps

After completing setup:

1. Explore the Codebase: Review the Architecture Documentation
2. Run Demo Scripts: Understand how components work
3. Read API Documentation: Learn the Services API
4. Check Contributing Guidelines: Review Contributing Guide
5. Start Development: Begin with small changes or bug fixes

Additional Resources

• Architecture Documentation: Technical architecture details
• API Reference: Complete API documentation
• Feature Documentation: Feature specifications
• Main README: Project overview and usage

---

Setup Guide Version: 1.0.0
Last Updated: January 2025
Maintainer: Development Team