codeflash-internal/django/aiservice/CLAUDE.md

AIService — Claude Code Instructions

Project Overview

Django-Ninja backend powering CodeFlash's AI-driven code optimization. Handles LLM interactions, test generation, and optimization workflows. Runs under ASGI via uvicorn — all endpoints must be async def.

Commands

# Install dependencies
uv sync
uv sync --group dev

# Run development server
uv run uvicorn aiservice.asgi:application --reload

# Run all tests
uv run pytest

# Run a single test file
uv run pytest tests/optimizer/test_optimizer.py

# Run a specific test
uv run pytest tests/optimizer/test_optimizer.py::test_function_name -v

# Type checking
uv run mypy .
uv run ty check

# Linting (auto-fixes enabled)
uv run ruff check .
uv run ruff format .

Architecture

All REST endpoints use Django-Ninja with type-safe Pydantic schemas. APIs are defined in aiservice/urls.py. Always use aiservice/llm.py for LLM calls — never call provider APIs directly.

LLM prompts are stored as .md files alongside their modules (e.g., optimizer/system_prompt.md).

Multi-Language Handler System

core/languages/ has per-language modules (python, js_ts, java) that register handlers via core/registry. Each handler implements protocols from core/protocols/. Routers in core/shared/ dispatch to the correct handler based on the language field in the request schema.

To add a new language: create a handler in core/languages/<lang>/, register it in __init__.py, implement the required protocol methods.

Key Patterns

• libcst, not ast: Always use libcst to preserve formatting when modifying code.
• Pydantic schemas: All request/response models use Pydantic BaseModel or ninja.Schema.
• Async + TaskGroup: Most endpoints are async. Use asyncio.TaskGroup for concurrent operations.
• Context classes: Optimizer and testgen use context classes (BaseOptimizerContext, BaseTestGenContext) to manage state and prompts.
• Lazy imports in routers: Routers use imports inside function bodies to avoid circular dependencies.

Django-Ninja Gotchas

• No automatic exception handling like DRF — use get_object_or_404 explicitly.
• Error handling requires custom code (no built-in exception-to-response mapping).
• Auth: HttpBearer must come before django_auth in auth lists to avoid CSRF errors.

Testing

• Tests live in tests/ organized by feature: optimizer/, testgen/, integration/, validators/
• Root conftest.py for shared fixtures
• Use @pytest.mark.asyncio for async endpoint tests
• Helper factories in test files: create_optimizer_context(), create_refiner_context()

Code Style

• Line length: 120 characters
• Python: 3.12+ syntax
• Comments: Minimal — explain "why", not "what"
• Docstrings: Don't add unless explicitly requested