Skip to main content

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.

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.

​
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, 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

AvoidPrefer
src.afk.agents.Agentafk.agents.Agent
afk.agents.core.base.Agentafk.agents.Agent
afk.core.runner.api.RunnerAPIMixinafk.core.Runner
afk.tools.core.decorator.toolafk.tools.tool
afk.llms.builder.LLMBuilderafk.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

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.