BAML

BAML

# Clone and navigate to the project
cd level-3-code/large_scale_classification

# Install runtime dependencies (for running the system)
uv sync

# OR install with development dependencies (for contributing/development)
uv sync --extra dev

# Set up environment variables
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

# Convert BAML files to Python client code
uv run baml-cli generate

# Run the interactive classification system
uv run python src/main.py

src/
├── main.py                    # Entry point
├── classification/            # Core classification logic
│   ├── pipeline.py           # Main orchestrator
│   ├── embeddings.py         # OpenAI embedding service
│   ├── narrowing.py          # Category narrowing strategies
│   ├── selection.py          # LLM-based final selection
│   └── vector_store.py       # ChromaDB vector store
├── data/                     # Data management
│   ├── category_loader.py    # Category loading and processing
│   └── models.py             # Pydantic data models
├── config/                   # Configuration
│   └── settings.py           # Application settings
└── shared/                   # Shared utilities
    ├── logger.py             # Structured logging
    ├── constants.py          # Application constants
    └── enums.py              # Enums and types

# Build the vector store from categories
python scripts/build_vector_store.py

# Force rebuild (e.g., after changing embedding models)
python scripts/build_vector_store.py --force-rebuild

narrowing_strategy = NarrowingStrategy.HYBRID  # EMBEDDING, HYBRID, or LLM
max_narrowed_categories = 5  # Number of candidates to pass to final selection

# Run all tests (unit + integration)
cd tests
python run_tests.py

# Run specific test types
python run_tests.py --unit                  # Unit tests only (fast, no API calls)
python run_tests.py --narrowing-accuracy    # Narrowing accuracy integration test
python run_tests.py --selection-accuracy    # Selection accuracy integration test
python run_tests.py --pipeline-accuracy     # Complete pipeline integration test
python run_tests.py --all                   # All tests explicitly

# Compare results across test runs
python tests/compare_results.py --narrowing file1.json file2.json

# Unit tests (from project root)
uv run pytest tests/unit/classification/pipeline_test.py -v
uv run pytest tests/unit/classification/selection_test.py -v

# Integration tests (from tests/integration)
cd tests/integration
python test_pipeline_accuracy.py

# Required - the only thing needed in .env
OPENAI_API_KEY=your_api_key_here

class Settings(BaseSettings):
    """Application configuration settings."""

    # OpenAI Configuration
    openai_api_key: str  # Loaded automatically from .env. Don't put your key here
    embedding_model: str = "text-embedding-3-small"
    
    # Classification Strategy
    narrowing_strategy: NarrowingStrategy = NarrowingStrategy.HYBRID
    max_narrowed_categories: int = 5
    
    # Hybrid Strategy Specific Settings
    max_embedding_candidates: int = 10  # How many categories embedding stage returns
    max_final_categories: int = 3       # How many categories LLM stage returns
    
    # Data Configuration
    categories_file_path: pathlib.Path = CWD.parents[1] / C.DATA / C.CATEGORIES_TXT

/Appliances/Refrigerators/French Door Refrigerators
/Appliances/Dishwashers/Built-in Dishwashers
/Appliances/Appliance Parts/Dishwasher Parts

# 1. Update configuration settings
# Edit src/config/settings.py - for example:
#   max_narrowed_categories = 10  (was 5)
#   max_embedding_candidates = 50  (was 10)

# 2. Run pipeline test with version tracking
uv run python tests/integration/test_pipeline_accuracy.py --save-as v7 --description "embedding 50, llm 10, model upgrade"

# 3. View results in Streamlit app
uv run streamlit run ui/app.py

# 4. Compare with previous versions in the UI
# The app will show performance comparisons across all saved versions

class Settings(BaseSettings):
    # Strategy Selection
    narrowing_strategy: NarrowingStrategy = NarrowingStrategy.HYBRID
    
    # Performance Tuning
    max_narrowed_categories: int = 5        # Final candidates passed to LLM
    max_embedding_candidates: int = 10      # Embedding stage candidates (hybrid only)
    max_final_categories: int = 3           # LLM stage candidates (hybrid only)
    
    # Model Selection
    embedding_model: str = "text-embedding-3-small"  # or "text-embedding-3-large"

uv run streamlit run ui/app.py

# Save test results with version and description
uv run python tests/integration/test_pipeline_accuracy.py --save-as v6 --description "baseline configuration"
uv run python tests/integration/test_pipeline_accuracy.py --save-as v7 --description "increased embedding candidates to 50"
uv run python tests/integration/test_pipeline_accuracy.py --save-as v8 --description "upgraded to text-embedding-3-large"

from src.classification.pipeline import ClassificationPipeline

# Initialize pipeline
pipeline = ClassificationPipeline()

# Classify text
result = pipeline.classify("Samsung 17.5-cu ft French door refrigerator")

print(f"Category: {result.category.name}")
print(f"Confidence: {result.confidence}")
print(f"Processing time: {result.processing_time_ms:.1f}ms")
print(f"Candidates: {[c.name for c in result.candidates]}")