mlcbakery: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MLC Bakery is a machine learning data and model management system with provenance tracking, built with FastAPI and SQLAlchemy. It provides RESTful APIs for managing ML model lineage, datasets, collections, and activities with support for Croissant metadata validation.

Architecture

The application follows a layered architecture:

1. API Layer (mlcbakery/api/) - FastAPI routers and endpoints organized by resource type
2. Schema Layer (mlcbakery/schemas/) - Pydantic models for request/response validation
3. Model Layer (mlcbakery/models.py) - SQLAlchemy ORM models for database entities
4. Database Layer (mlcbakery/database.py) - Database connection and session management
5. Auth Layer (mlcbakery/auth/) - Multiple authentication strategies (JWT, Admin Token, Passthrough)
6. Storage Layer (mlcbakery/storage/) - GCP storage integration for artifacts
7. MCP Server (mlcbakery/mcp/) - Model Context Protocol server implementation

Key architectural patterns:

• Async/await throughout for non-blocking I/O
• Dependency injection for database sessions and authentication
• Pydantic for data validation
• SQLAlchemy with async support for database operations
• OpenTelemetry instrumentation for observability

Development Commands

Setup and Installation

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Set up environment variables
cp env.example .env

# Install Python 3.12 if needed
uv python install 3.12

# Install dependencies (use uv sync for more reliable installation)
uv sync --python 3.12

Running the Application

Local Development:

# Run the FastAPI server with auto-reload
uv run uvicorn mlcbakery.main:app --reload --host 0.0.0.0 --port 8000

Docker Development:

# Start all services (postgres, typesense, api, mcp, caddy reverse proxy)
docker compose up -d

# Create database and run migrations
docker compose exec db psql -U postgres -c "create DATABASE mlcbakery;"
docker compose exec api alembic upgrade head