> ## 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.

# Full Module Reference

> Module inventory and responsibilities.

The Agent Forge Kit (AFK) Python SDK is organized into top-level packages, each owning a distinct responsibility. This page summarizes the package map, key public imports, and extension boundaries.

Use this reference when you need to find which package owns a capability. For field-level details, read the focused reference pages linked from the sidebar.

## Module dependencies

The AFK architecture is organized around a few stable boundaries:

* **`afk.agents`** owns declarative agent configuration, policy, prompts, skills, delegation metadata, and A2A contracts.
* **`afk.core`** owns execution: runner lifecycle, streaming, interaction providers, delegation scheduling, checkpointing, memory wiring, and telemetry wiring.
* **`afk.llms`** owns model provider adapters, runtime policies, structured output helpers, routing, caching, and LLM request/response types.
* **`afk.tools`** owns tool definitions, registries, hooks, middleware, sandbox profiles, and prebuilt runtime tools.

### Extension points

The framework is designed to be extended at specific protocol boundaries. **Do not subclass internal classes**. Instead, implement these protocols:

* **`InteractionProvider`** (`afk.core`): Build custom human-in-the-loop interfaces (for example Slack, Discord, or web approval UIs).
* **`MemoryStore`** (`afk.memory`): Add support for new databases (Mongo, DynamoDB).
* **`LLMProvider`** (`afk.llms`): Integrate new model providers (local inference, exotic APIs).
* **`TelemetrySink`** (`afk.observability`): Export metrics/traces to custom backends (Datadog, Honeycomb).

***

## `afk.agents`

Agent definitions, lifecycle types, delegation, policy, A2A protocol, and error hierarchy.

**Sub-modules:**

| Sub-module              | Responsibility                                                                                                                                                         |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `afk.agents.core`       | `Agent` and `BaseAgent` definitions, `ChatAgent` variant.                                                                                                              |
| `afk.agents.types`      | Runtime types: `AgentResult`, `AgentRunEvent`, `AgentRunHandle`, `AgentState`, `PolicyEvent`, `PolicyDecision`, `FailSafeConfig`, `UsageAggregate`, execution records. |
| `afk.agents.policy`     | `PolicyEngine`, `PolicyRule`, `PolicyEvaluation`, policy subject inference.                                                                                            |
| `afk.agents.delegation` | `DelegationPlan`, `DelegationNode`, `DelegationEdge`, `RetryPolicy`, `JoinPolicy`, `DelegationResult`.                                                                 |
| `afk.agents.a2a`        | `InternalA2AProtocol`, A2A auth providers (`AllowAllA2AAuthProvider`, `APIKeyA2AAuthProvider`, `JWTA2AAuthProvider`), `A2AServiceHost`, delivery stores.               |
| `afk.agents.contracts`  | `AgentCommunicationProtocol`, `AgentInvocationRequest`, `AgentInvocationResponse`, `AgentDeadLetter`.                                                                  |
| `afk.agents.prompts`    | `PromptStore`, prompt file resolution, template rendering.                                                                                                             |
| `afk.agents.lifecycle`  | Checkpoint versioning, schema migration, runtime helpers (circuit breaker, effect journal, state snapshots).                                                           |
| `afk.agents.skills`     | `SkillStore`, `SkillDoc`, SKILL.md parsing, checksum verification, and process-wide caching.                                                                           |
| `afk.agents.security`   | Prompt-injection sanitization, untrusted tool-output redaction, and channel markers for trusted vs untrusted content.                                                  |
| `afk.agents.errors`     | Full error hierarchy: `AgentError`, `AgentExecutionError`, `AgentCancelledError`, `SubagentRoutingError`, etc.                                                         |

**Key imports:**

```python theme={null}
from afk.agents import Agent, AgentResult, AgentRunEvent, PolicyEngine, PolicyRule
from afk.agents import DelegationPlan, DelegationNode, FailSafeConfig
from afk.agents import JWTA2AAuthProvider, A2AServiceHost
```

## `afk.core`

Runner execution engine, streaming, interaction providers, and delegation engine.

**Sub-modules:**

| Sub-module             | Responsibility                                                                                                                                              |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `afk.core.runner`      | `Runner` class with `run()`, `run_sync()`, `run_handle()`, `run_stream()`, `resume()`, `compact_thread()`. `RunnerConfig` for safety and behavior defaults. |
| `afk.core.streaming`   | `AgentStreamHandle`, `AgentStreamEvent`, stream event constructors (`text_delta`, `tool_started`, `stream_completed`).                                      |
| `afk.core.interaction` | `InteractionProvider` protocol, `HeadlessInteractionProvider`, `InMemoryInteractiveProvider`.                                                               |
| `afk.core.runtime`     | `DelegationEngine`, `DelegationPlanner`, `DelegationScheduler`, backpressure and graph validation.                                                          |

**Key imports:**

```python theme={null}
from afk.core import Runner, RunnerConfig
from afk.core import AgentStreamHandle, AgentStreamEvent
from afk.core import InteractionProvider, HeadlessInteractionProvider
from afk.core import DelegationEngine
```

## `afk.llms`

LLM client builder, provider registry, runtime policies, caching, routing, middleware, and type definitions.

**Sub-modules:**

| Sub-module            | Responsibility                                                                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `afk.llms.builder`    | `LLMBuilder` -- fluent builder for constructing LLM client instances.                                                                            |
| `afk.llms.providers`  | Provider registry: `OpenAIProvider`, `LiteLLMProvider`, `AnthropicAgentProvider`, `register_llm_provider()`.                                     |
| `afk.llms.runtime`    | `LLMClient` with production policies: `RetryPolicy`, `TimeoutPolicy`, `RateLimitPolicy`, `CircuitBreakerPolicy`, `HedgingPolicy`, `CachePolicy`. |
| `afk.llms.routing`    | Router registry: `create_llm_router()`, `register_llm_router()`.                                                                                 |
| `afk.llms.cache`      | Cache backends: `create_llm_cache()`, in-memory and Redis implementations.                                                                       |
| `afk.llms.middleware` | `MiddlewareStack` for request/response transformation pipelines.                                                                                 |
| `afk.llms.types`      | `LLMRequest`, `LLMResponse`, `Message`, `ToolCall`, `Usage`, streaming event types.                                                              |
| `afk.llms.config`     | `LLMConfig` dataclass for model configuration.                                                                                                   |
| `afk.llms.profiles`   | Production/development profile presets.                                                                                                          |
| `afk.llms.errors`     | `LLMError`, `LLMTimeoutError`, `LLMRetryableError`, etc.                                                                                         |

**Key imports:**

```python theme={null}
from afk.llms import LLMBuilder, LLMClient, LLMRequest, LLMResponse, Message
from afk.llms import RetryPolicy, TimeoutPolicy, CircuitBreakerPolicy
from afk.llms import LLMConfig, LLMSettings, PROFILES
```

## `afk.tools`

Tool definition, registry, hooks, middleware, security, and prebuilt runtime tools.

**Sub-modules:**

| Sub-module            | Responsibility                                                                          |
| --------------------- | --------------------------------------------------------------------------------------- |
| `afk.tools.core`      | `tool` decorator, `ToolSpec`, `ToolContext`, `ToolResult`, `ToolRegistry`.              |
| `afk.tools.security`  | `SandboxProfile`, `SandboxProfileProvider`, `SecretScopeProvider`, argument validation. |
| `afk.tools.prebuilts` | Built-in runtime tools (file read, directory list, command execution, skill tools).     |
| `afk.tools.registry`  | Shared registry and registry middleware helpers.                                        |

**Key imports:**

```python theme={null}
from afk.tools import tool, ToolResult, ToolContext
from afk.tools.security import SandboxProfile, SecretScopeProvider
```

## `afk.memory`

Pluggable memory stores, compaction, retention policies, long-term memory, vector search, and thread state persistence.

**Sub-modules:**

| Sub-module             | Responsibility                                                                                                  |
| ---------------------- | --------------------------------------------------------------------------------------------------------------- |
| `afk.memory.store`     | `MemoryStore` abstract base class, `MemoryCapabilities` declarations.                                           |
| `afk.memory.types`     | `MemoryEvent`, `LongTermMemory`, `JsonValue`, retention policy models.                                          |
| `afk.memory.lifecycle` | `apply_event_retention()`, `apply_state_retention()`, `compact_thread_memory()`, `MemoryCompactionResult`.      |
| `afk.memory.vector`    | `cosine_similarity()`, vector scoring utilities for embedding-based search.                                     |
| `afk.memory.factory`   | `create_memory_store_from_env()` factory for environment-based backend selection.                               |
| `afk.memory.adapters`  | Backend implementations: `InMemoryMemoryStore`, `SQLiteMemoryStore`, `PostgresMemoryStore`, `RedisMemoryStore`. |

**Key imports:**

```python theme={null}
from afk.memory import MemoryStore, RetentionPolicy, compact_thread_memory
from afk.memory import InMemoryMemoryStore
from afk.memory.adapters.sqlite import SQLiteMemoryStore
from afk.memory.adapters.postgres import PostgresMemoryStore
from afk.memory.adapters.redis import RedisMemoryStore
from afk.memory.types import MemoryEvent, LongTermMemory
```

## `afk.queues`

Task queue abstraction, worker lifecycle, failure classification, and metrics.

**Sub-modules:**

| Sub-module             | Responsibility                                      |
| ---------------------- | --------------------------------------------------- |
| `afk.queues.base`      | Base queue types and enqueue/dequeue contracts.     |
| `afk.queues.contracts` | Queue protocol definitions.                         |
| `afk.queues.factory`   | Queue backend factory for creating queue instances. |
| `afk.queues.worker`    | Worker lifecycle management and task dispatch.      |
| `afk.queues.metrics`   | Queue-level operational metrics.                    |

**Key imports:**

```python theme={null}
from afk.queues import TaskQueue, TaskWorker
```

## `afk.observability`

Telemetry collection, projection, and export for runtime monitoring.

**Sub-modules:**

| Sub-module                     | Responsibility                                                                           |
| ------------------------------ | ---------------------------------------------------------------------------------------- |
| `afk.observability.models`     | `RunMetrics` dataclass with aggregated run statistics.                                   |
| `afk.observability.contracts`  | Span and metric name constants (`SPAN_AGENT_RUN`, `METRIC_AGENT_LLM_CALLS_TOTAL`, etc.). |
| `afk.observability.projectors` | Projection functions that transform run results into `RunMetrics`.                       |
| `afk.observability.exporters`  | `ConsoleRunMetricsExporter` and other output formatters.                                 |
| `afk.observability.backends`   | Telemetry sink creation (`create_telemetry_sink`).                                       |

**Key imports:**

```python theme={null}
from afk.observability.models import RunMetrics
from afk.observability.contracts import SPAN_AGENT_RUN, METRIC_AGENT_LLM_CALLS_TOTAL
from afk.observability.exporters.console import ConsoleRunMetricsExporter
```

## `afk.evals`

Eval suite execution, assertion contracts, budget constraints, and report serialization.

**Sub-modules:**

| Sub-module            | Responsibility                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------ |
| `afk.evals.suite`     | `run_suite()` and `arun_suite()` entrypoints.                                              |
| `afk.evals.executor`  | Single-case execution via `run_case()` and `arun_case()`.                                  |
| `afk.evals.models`    | `EvalCase`, `EvalCaseResult`, `EvalSuiteConfig`, `EvalSuiteResult`, `EvalAssertionResult`. |
| `afk.evals.contracts` | `EvalAssertion`, `AsyncEvalAssertion`, `EvalScorer` protocols.                             |
| `afk.evals.budgets`   | `EvalBudget` dataclass and `evaluate_budget()` function.                                   |
| `afk.evals.reporting` | `suite_report_payload()`, `write_suite_report_json()`.                                     |
| `afk.evals.golden`    | `write_golden_trace()`, `compare_event_types()` for deterministic trace comparison.        |

**Key imports:**

```python theme={null}
from afk.evals import run_suite, EvalBudget
from afk.evals.models import EvalCase, EvalSuiteConfig, EvalSuiteResult
from afk.evals.reporting import write_suite_report_json
from afk.evals.golden import compare_event_types
```

## `afk.mcp`

Model Context Protocol server implementation, tool store, and server registration.

**Sub-modules:**

| Sub-module       | Responsibility                                                  |
| ---------------- | --------------------------------------------------------------- |
| `afk.mcp.server` | MCP protocol handler.                                           |
| `afk.mcp.store`  | Tool store registry and utility functions for MCP tool loading. |

**Key imports:**

```python theme={null}
from afk.mcp import get_mcp_store
```

## `afk.messaging`

Protocol-first agent-to-agent messaging exports.

**Sub-modules:**

| Sub-module       | Responsibility                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------- |
| `afk.messaging`  | Public re-exports for A2A contracts, envelopes, auth providers, hosts, and delivery stores. |
| `afk.agents.a2a` | Internal implementation modules for protocol, auth, delivery, hosting, and Google adapter.  |

**Key imports:**

```python theme={null}
from afk.messaging import InternalA2AEnvelope, InternalA2AProtocol
from afk.messaging import AgentInvocationRequest, AgentInvocationResponse
```