AI Assistant Guide

This page is written for coding assistants (GitHub Copilot, Cursor, etc.) and for humans reviewing AI-generated changes.

Repository Mental Model

When modifying behavior, map the change to one or more layers:

1. Phrase construction (lingo/phrase.py)
2. Runtime dispatch/execution (lingo/celery/language.py)
3. Transport serialization (lingo/celery/protocol.py)
4. Persistence/progress (lingo/storage/mongo/journal.py)
5. Artifact storage (lingo/bucket/archive.py)
6. CLI surface (lingo/cli.py)

High-Confidence Change Workflow

1. Add or update behavior in one layer at a time.
2. Add tests closest to that layer first.
3. Run focused tests before broad test suites.
4. Update guide docs if user-facing behavior changed.
5. Ensure docstrings are Google style for new public APIs.

Invariants to Preserve

• Job status transitions should be monotonic.
• Serialized payloads must remain backward-compatible where practical.
• Fallback paths (distributed to local, compiled to simple) should preserve correctness.
• CLI should stay non-interactive and script-friendly.

Docstring Standard

Use Google style for public APIs:

• short summary line
• Args: section
• Returns: section
• Raises: section when relevant

This style is required for clean mkdocstrings output.

When Unsure

Before changing semantics, inspect:

• tests in tests/ matching the subsystem
• FastAPI example usage in examples/fastapi/
• existing event names and status handling in journal/language modules