How contrastoai/cartai works
Project type and purpose
• CartAI is a Python-based command-line tool whose primary purpose is to generate end-to-end documentation (e.g. README files, PR diffs) through code parsing and large-language-model (LLM) integration.
File structure
• Top-level directories:
• cartai/ (the main package)
– cli/ (CLI entrypoint & commands)
– core/ (domain logic: code parsing)
– llm_agents/ (LLM wrappers, templating, utilities)
• examples/ (Jupyter notebooks demonstrating usage)
• tests/ (unit tests)
• Configuration & tooling: Makefile, pyproject.toml, pre-commit, .python-version
• No separate “frontend” or “backend”—it’s a single CLI application with layered modules.
Key insights from the README
• The workflow: user invokes a Makefile/CLI command → CartAI parses code → CartAI builds prompts via Jinja templates → CartAI calls an external LLM API → CartAI outputs documentation files.
Main components
a. CLI Layer
• Entrypoint (main.py)
• Commands: readme, pr_diff
b. Core Layer
• code_parser.py (ingests user code, AST extraction, metrics)
c. LLM Agents Layer
• documenter.py (orchestrates prompt construction & LLM calls)
• utils.py (shared helpers)
• templates/ (readme.jinja, pr_diff.jinja)
d. External Services
• LLM API (e.g. OpenAI)
e. File System
• Input: user’s codebase (src files)
• Output: generated docs (README_new.md, PR summaries)
f. Supporting Infrastructure
• Tests (unit tests under tests/)
• CI workflows (.github/workflows)
• Pre-commit & linting
Relationships & data flow
1) User runs make run_readme or cartai readme → invokes CLI Layer
2) CLI Layer calls Core Layer to parse source code
3) Core Layer returns parsed data structures to LLM Agents Layer
4) LLM Agents Layer fills Jinja templates with parsed data → generates prompt
5) LLM Agents Layer sends prompt to External LLM API, receives response
6) CLI Layer writes response to file system (e.g. README_new.md)
7) Tests validate Core & LLM Agents modules in isolation
Architectural patterns & design principles
• Layered architecture (Presentation/CLI → Domain/Core → Integration/LLM Agents → Infrastructure/API)
• Adapter pattern (wrapping the external LLM API behind documenter.py)
• Command pattern (each CLI command is a discrete unit in cartai/cli/commands)
• Template-driven design (Jinja templates define prompt structure and output format)
Technologies & frameworks
• Python 3.x
• Click (or built-in argparse) for CLI (main.py)
• Jinja2 for templating
• pytest for testing
• pre-commit, uv for quality & dependency management