---
description: Project context and navigation hub - loaded by agent_workflow.mdc
globs: AGENTS.md, .cursor/rules/*.mdc
alwaysApply: false
---
# AGENTS.md Usage Guidelines

**⚠️ IMPORTANT: This rule is loaded by agent_workflow.mdc. Do not read directly.**

## Purpose and Scope

**AGENTS.md** serves as the **project onboarding document** and **navigation hub** for the Trax project. It provides high-level context, quick start information, and links to detailed documentation.

## Project Context

Trax is a subproject within the my-ai-projects ecosystem that uses the ultra-fast `uv` package manager for Python dependency management. The project inherits all API tokens from the root project's `.env` file located at `../../.env`.

**Core Mission**: Deterministic, iterative media transcription platform that transforms raw audio/video into structured, enhanced, and searchable text content through progressive AI-powered processing.

## When to Reference AGENTS.md

- **Project Overview**: Understanding what Trax is and its core mission
- **Quick Start**: Essential commands and development setup
- **Current Status**: Project phase, completed work, and next milestones
- **Navigation**: Finding detailed documentation and resources
- **Team Context**: Understanding the project's place in the my-ai-projects ecosystem

## Quick Start

### Essential Commands
```sh
# Install dependencies in development mode
uv pip install -e ".[dev]"

# Start the development server
uv run python src/main.py

# Run all tests with coverage
uv run pytest

# Format and lint code
uv run black src/ tests/
uv run ruff check --fix src/ tests/
```

### Development Workflow
```sh
# Get next task to work on
./scripts/tm_master.sh next

# Start working on a task
./scripts/tm_master.sh start 15

# Complete a task
./scripts/tm_master.sh done 15

# Search for tasks
./scripts/tm_master.sh search whisper
```

## Project Status

### Current Phase: Foundation (Weeks 1-2)
**Goal**: Working CLI transcription tool

**✅ Completed**:
- PostgreSQL database setup with JSONB
- YouTube metadata extraction and download pipeline
- CLI implementation with Click

**🚧 Ready for Implementation**:
- Basic Whisper transcription service (v1)
- JSON/TXT export functionality

**🎯 Next Milestones**:
- Process 5-minute audio in <30 seconds
- 95% transcription accuracy on clear audio

### Version Progression
- **v1**: Basic transcription (95% accuracy, <30s for 5min audio)
- **v2**: AI enhancement (99% accuracy, <35s processing)
- **v3**: Multi-pass accuracy (99.5% accuracy, <25s processing)
- **v4**: Speaker diarization (90% speaker accuracy)

## Key Tools & Features

### Research Agent
Powerful Streamlit Research Agent with Perplexity AI for real-time web search:

```sh
# Launch the web interface
python launch_research_agent.py

# Quick CLI research
python -m src.cli.main research "your research question"
```

### Taskmaster Integration
Fast task management using CLI directly:

```sh
# Get project overview
task-master list

# Find next task
task-master next

# Show task details
task-master show <id>

# Start working on a task
./scripts/tm_workflow_simple.sh start <id>

# Update progress
./scripts/tm_workflow_simple.sh update <id> <message>

# Complete a task
./scripts/tm_workflow_simple.sh complete <id>
```

### Cursor Rules System
Advanced development rules for consistent code patterns:

```sh
# Analyze current rules
./scripts/generate_rules.sh --analyze

# Generate rules for new features
./scripts/generate_rules.sh --generate src/services --type python
```

## Common Workflows

### Adding New Dependencies
```sh
# Add production dependency
uv pip install package-name

# Add development dependency
uv pip install package-name --dev

# Update requirements.txt
uv pip compile pyproject.toml -o requirements.txt
```

### Database Changes
```sh
# Create new migration
alembic revision -m "description"

# Apply migrations
alembic upgrade head

# Check current version
alembic current
```

### Debugging
```sh
# Start interactive Python shell
uv run ipython

# Run with debug logging
uv run python -m src.main --debug
```

## Performance Targets

### Audio Processing
- **Model**: distil-large-v3 for M3 optimization (20-70x speed improvement)
- **Preprocessing**: Convert to 16kHz mono WAV (3x data reduction)
- **Memory**: <2GB for v1 pipeline

### Caching Strategy
- **Embeddings**: 24h TTL
- **Analysis**: 7d TTL
- **Queries**: 6h TTL
- **Compression**: LZ4 for storage efficiency

## Documentation Separation

- **AGENTS.md**: Project context, quick start, navigation
- **Cursor Rules**: Technical implementation patterns and constraints
- **Detailed Docs**: In-depth technical documentation in `docs/`

## Rule Loading Information

**This rule is automatically loaded by [agent_workflow.mdc](mdc:.cursor/rules/agent_workflow.mdc) for all operations.**

**For decision-making and workflow guidance, see [agent_workflow.mdc](mdc:.cursor/rules/agent_workflow.mdc).**

## Reference Documentation

### Development Rules & Patterns
- **[Cursor Rules](./.cursor/rules/)** - Detailed development rules and patterns
- **[Implementation Guide](./docs/CURSOR_RULES_IMPLEMENTATION.md)** - Setup and maintenance
- **[Rule Templates](./.cursor/rules/templates/rule-templates.mdc)** - Rule creation templates

### Architecture & Design
- **[Development Patterns](./docs/architecture/development-patterns.md)** - Historical learnings
- **[Audio Processing](./docs/architecture/audio-processing.md)** - Audio pipeline architecture
- **[Iterative Pipeline](./docs/architecture/iterative-pipeline.md)** - Version progression

### Project Reports
- **[Product Vision](./docs/reports/06-product-vision.md)** - Product goals and roadmap
- **[Technical Migration](./docs/reports/05-technical-migration.md)** - Migration strategy
- **[Executive Summary](./EXECUTIVE-SUMMARY.md)** - High-level project overview

### Development Tools
- **[Taskmaster Helper Scripts](./scripts/README_taskmaster_helpers.md)** - CLI helper scripts
- **[Research Agent](./docs/RESEARCH_AGENT.md)** - Research agent documentation
- **[CLI Reference](./docs/CLI.md)** - Command-line interface documentation

### Test Data
- **[Test Videos](./videos.csv)** - Collection of YouTube URLs for testing

## Quick Reference

### File Organization
- Keep each file under 300 LOC (350 max if justified)
- Use meaningful file and function names
- Group related functionality in modules

### Code Style
- **Python Version**: 3.11+ with strict type checking
- **Formatting**: Black with line length 100
- **Linting**: Ruff with auto-fix enabled
- **Type Checking**: MyPy strict mode

### Critical Patterns
- **Backend-First Development**: Get data layer right before UI
- **Test-First**: Write test, then implementation
- **Download-First**: Never stream media, always download first
- **Real Files Testing**: Use actual audio files, no mocks
- **Protocol-Based Services**: Use typing.Protocol for all service interfaces

## Troubleshooting

### Common Issues
- **Missing .env file**: Ensure `../../.env` exists in the root project
- **Import errors**: Check that dependencies are installed with `uv pip install -e ".[dev]"`
- **Type errors**: Run `uv run mypy src/` to identify issues
- **Formatting issues**: Run `uv run black src/ tests/` to auto-format

### Getting Help
- Review existing code patterns in `src/` directory
- Consult the project maintainers for architecture decisions

## Best Practices

- **Use Cursor rules** for technical implementation guidance
- **Maintain consistency** between documentation and implementation
- **Update documentation** when project status or workflows change
- **Link to specific rules** when referencing technical patterns