6.4 KiB

Raw Blame History

AGENTS.md - Project Onboarding

AGENTS.md is for defining agent instructions. It ONLY works in the project's root directory.

It's perfect for projects that need simple, readable instructions without the overhead of structured rules.

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.

Quick Start

Essential Commands

# 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

# 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:

# 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:

# 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:

# 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

# 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

# Create new migration
alembic revision -m "description"

# Apply migrations
alembic upgrade head

# Check current version
alembic current

Debugging

# 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

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

Check the CLAUDE.md file for detailed project context
Review existing code patterns in src/ directory
Consult the project maintainers for architecture decisions

Reference Documentation

Development Rules & Patterns

Cursor Rules - Detailed development rules and patterns
Implementation Guide - Setup and maintenance
Rule Templates - Rule creation templates

Architecture & Design

Development Patterns - Historical learnings
Audio Processing - Audio pipeline architecture
Iterative Pipeline - Version progression

Project Reports

Product Vision - Product goals and roadmap
Technical Migration - Migration strategy
Executive Summary - High-level project overview

Development Tools

Taskmaster Helper Scripts - CLI helper scripts
Research Agent - Research agent documentation
CLI Reference - Command-line interface documentation

Test Data

Test Videos - 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

This document provides quick access to essential project information. For detailed development rules and patterns, see the Cursor Rules directory.

6.4 KiB Raw Blame History