Public API Rules

​

Contract

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

​

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, Configuration Reference, examples, and generated agent-facing docs.

​

Preferred examples

from afk.agents import Agent, FailSafeConfig
from afk.core import Runner, RunnerConfig
from afk.tools import ToolContext, tool

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

​

Change checklist

• 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

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