> ## Documentation Index
> Fetch the complete documentation index at: https://afk.arpan.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Public API Rules

> Maintainer rules for preserving AFK's public import contract.

This page is for AFK maintainers. It explains how to change public exports without making downstream code or docs confusing.

For the user-facing import table, see [API Reference](/library/api-reference).

## Contract

The public API is the set of names exported by package-level `__init__.py` files:

* `afk.agents`
* `afk.core`
* `afk.tools`
* `afk.llms`
* `afk.memory`
* `afk.queues`
* `afk.mcp`
* `afk.messaging`
* `afk.observability`
* `afk.evals`

Public docs and examples should import from these package surfaces. They should not use `src.afk` imports or deep implementation modules such as `afk.core.runner.api`.

## Rules for maintainers

1. If a downstream user should import a symbol, export it from the package-level `__init__.py`.
2. If a symbol is not exported, do not use it in builder docs or examples.
3. Keep `Agent` and `Runner` separate: `Agent` comes from `afk.agents`; `Runner` comes from `afk.core`.
4. Prefer protocols, dataclasses, Pydantic models, and explicit error classes for public contracts.
5. When removing or renaming a public symbol, update migration docs and tests in the same change.
6. When changing a public constructor, update [API Reference](/library/api-reference), [Configuration Reference](/library/configuration-reference), examples, and generated agent-facing docs.

## Preferred examples

```python theme={null}
from afk.agents import Agent, FailSafeConfig
from afk.core import Runner, RunnerConfig
from afk.tools import ToolContext, tool
```

```python theme={null}
from afk.llms import LLMBuilder, RetryPolicy, TimeoutPolicy
from afk.memory import InMemoryMemoryStore, SQLiteMemoryStore
from afk.queues import InMemoryTaskQueue, TaskWorker
```

## Imports to avoid in public docs

| Avoid                                | Prefer                |
| ------------------------------------ | --------------------- |
| `src.afk.agents.Agent`               | `afk.agents.Agent`    |
| `afk.agents.core.base.Agent`         | `afk.agents.Agent`    |
| `afk.core.runner.api.RunnerAPIMixin` | `afk.core.Runner`     |
| `afk.tools.core.decorator.tool`      | `afk.tools.tool`      |
| `afk.llms.builder.LLMBuilder`        | `afk.llms.LLMBuilder` |

Deep imports are acceptable in internal tests only when the test is specifically covering an internal unit. Integration tests and examples should exercise the public surface.

## Change checklist

Before merging a public API change:

* Update the relevant package `__all__`.
* Add or update tests that import through the public package.
* Update user-facing docs if a builder would see the changed behavior.
* Update maintainer docs if an invariant or subsystem boundary changed.
* Run `PYTHONPATH=src pytest -q` or targeted tests for the affected subsystem.
* Regenerate agent-facing docs with `./scripts/build_agentic_ai_assets.sh` when docs, examples, skill metadata, or navigation changes.

## Search commands

```bash theme={null}
rg -n "src\\.afk|import src\\.afk" docs README.md CONTRIBUTING.md ENV_VARS.md skills
rg -n "from afk\\.agents import Runner" docs README.md CONTRIBUTING.md ENV_VARS.md skills
rg -n "from afk\\.[a-z_]+\\.[a-z_]+\\." docs README.md CONTRIBUTING.md ENV_VARS.md skills
```

The last command intentionally finds deep imports for review. Some maintainer references may be valid, but builder docs should avoid them.