# {{PROJECT_NAME}} Agent

Canonical root-agent layout defined by framework conventions.

## Structure

- `agent.py` - public `@mode` entrypoints only
- `schemas.py` - public mode inputs, outputs, and params
- `playground.py` - Playground presets bound from `agent.py`
- `contract.toml` - public metadata and release version
- `pyproject.toml` - local development/runtime dependency manifest
- `runtime/` - root-agent runtime image metadata and Dockerfile
- `models/{{MODEL_KEY}}/model.py` - internal behavior composed by the public modes
- `models/{{MODEL_KEY}}/engine.py` - runtime loading and execution helpers
- `models/{{MODEL_KEY}}/vectors.py` - declared vector bindings when the model uses vectors
- `models/{{MODEL_KEY}}/runtime/` - model-scoped runtime image files
- `models/{{MODEL_KEY}}/tuning/` - tuning support only when explicitly enabled

## Authoring Rules

- The scaffold does not generate `modes.py`, `workflows/`, or `models = [...]` registries. Keep the public surface in `agent.py`.
- Root-agent containers must use `python -m aimp_sdk.agent_runner --module /app/agent.py`.
- Model runtime containers must use `python -m aimp_sdk.entrypoint --module /app/model.py`.
- Heavy runtime assets must be prepared during Docker build via a dedicated `runtime_preload.py` module, then loaded from fixed local paths at runtime.
- If you add vectors, declare them in `models/{{MODEL_KEY}}/vectors.py` and keep `.aimp/project.toml` vector aliases in sync.
- Vector-enabled modes require client `scope` at execution time.
- Playground image previews should use `image_id` and the local Playground cache. Public APIs should return clean IDs and metadata, not generated preview URLs.
- Do not download model weights in request-path code or in `Engine.build()`. Keep runtime loads local-only and explicit.

## Deploy

```bash
ai push
```
