theinterneti Core Conventions (TTA.dev)
Non-negotiable standards for all code in the TTA.dev repository.
Package Manager
Always use uv, never pip or poetry.
uv add package-name # Add dependency
uv sync --all-extras # Sync all dependencies
uv run pytest -v # Run via uv
Python Version & Types
- Python 3.12+ required
str | NonenotOptional[str]dict[str, Any]notDict[str, Any]- Google-style docstrings on all public functions
Primitives — Always Use Them
# ✅ Use primitives
workflow = RetryPrimitive(primitive=api_call, max_retries=3)
# ❌ Never write manual retry/timeout loops
for attempt in range(3): # WRONG
try: ...
Anti-Patterns
| ❌ Don't | ✅ Do |
|---|---|
try/except retry loops |
RetryPrimitive |
asyncio.wait_for() |
TimeoutPrimitive |
| Manual caching dicts | CachePrimitive |
| Global variables for state | WorkflowContext |
pip install |
uv add |
Optional[str] |
`str |
from primitives.X |
from ttadev.primitives.X |
State Management
Pass state via WorkflowContext, never global variables:
context = WorkflowContext(workflow_id="demo")
result = await workflow.execute(input_data, context)
LLM Provider Strategy
Always use get_llm_client() — never hardcode a model or base URL.
from ttadev.workflows.llm_provider import get_llm_client
cfg = get_llm_client()
# cfg.base_url, cfg.model, cfg.api_key, cfg.provider
Provider hierarchy for TTA.dev apps (automatic, zero config required):
- Ollama — default, always available, no API key needed (
qwen2.5:7b) - OpenRouter
:free— ifOPENROUTER_API_KEYis set - Paid models — if a paid key is configured
Never use nvidia/nemotron-3-super-120b-a12b:free — it is a reasoning-only
model that returns content: null. Any code reading response.content will crash.
Deep Reference
- Primitives API & patterns:
docs/agent-guides/primitives-patterns.md - Python standards:
docs/agent-guides/python-standards.md - LLM provider strategy:
docs/agent-guides/llm-provider-strategy.md - TODO management:
docs/agent-guides/todo-management.md