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

# State Managers

> Distributed domain managers communicating through English-language APIs

## Architecture

Unity's intelligence is distributed across specialized **state managers**, each owning a different aspect of the assistant's cognition:

```
CodeActActor (generates Python plans, calls primitives.* APIs)
    │
    ▼
State Managers (each runs its own async LLM tool loop)
    │
    ├── ContactManager        — people and relationships
    ├── KnowledgeManager      — domain facts, structured knowledge
    ├── TaskScheduler         — durable tasks, execution with live handles
    ├── TranscriptManager     — conversation history and search
    ├── GuidanceManager       — procedures, SOPs, how-to knowledge
    ├── FileManager           — file parsing and registry
    ├── ImageManager          — image storage, vision queries
    ├── FunctionManager       — user-defined functions
    ├── WebSearcher           — web research
    ├── SecretManager         — encrypted secret storage
    ├── BlacklistManager      — blocked contact details
    └── DataManager           — low-level data operations
```

Each manager exposes a small public surface — typically `ask` (read-only), `update` (mutations), and sometimes `execute` (start durable work). The Actor orchestrates them through code-first plans.

## English as API

The defining design choice: managers communicate through **natural-language interfaces**. The public methods take plain `text: str` parameters, not structured queries.

```python theme={null}
# ContactManager.ask — the parameter is English, not SQL
await primitives.contacts.ask("Who did we meet at the conference last month?")

# KnowledgeManager.update — the instruction is English, not a CRUD operation
await primitives.knowledge.update(
    "Record that the Henderson project deadline moved to March 15"
)
```

Each manager has its own internal LLM tool loop that interprets the English request and orchestrates lower-level tools (database queries, API calls, etc.) to fulfill it. The caller never sees the implementation details.

This matters because:

* **Managers are swappable.** The ContactManager could use a SQL database, a vector store, or an external CRM. The caller's code doesn't change.
* **The system is inspectable.** You can read the Actor's plan and understand what it's doing without reading implementation code.
* **Composition is natural.** The Actor can write `for contact in contacts: await primitives.knowledge.ask(f"What was {contact} working on?")` — the English flows through cleanly.

## Base class contracts

Every manager has an abstract base class (`base.py`) that defines the public API contract. The docstrings on these abstract methods **are** the API — they're attached to derived classes via `@functools.wraps` and visible to the LLM when the methods are exposed as tools.

```python theme={null}
class BaseContactManager(BaseStateManager):
    @abstractmethod
    async def ask(self, text: str, ...) -> SteerableToolHandle:
        """Answer questions about stored contacts.

        text : str
            The user's plain-English question
            (e.g. "Show me Alice's phone number.").
        """

    @abstractmethod
    async def update(self, text: str, ...) -> SteerableToolHandle:
        """Execute English instructions that create or change contacts.

        text : str
            The user's instruction
            (e.g. "Add Bob's email: bob@example.com").
        """
```

The base class docstrings are **implementation-agnostic** — they never reference internal tools, database schemas, or other managers. This creates a clean separation: the public API is stable even as the implementation evolves.

## Each manager runs its own LLM

This is important: when the Actor calls `primitives.contacts.ask(...)`, the ContactManager starts **its own** async LLM tool loop. That loop has its own system prompt, its own set of internal tools (search contacts, filter by field, etc.), and its own conversation context.

This means:

* The Actor's LLM doesn't need to know how contacts are stored
* The ContactManager's LLM is specialized for contact operations
* Each manager can use a different model if needed (fast model for simple lookups, powerful model for complex reasoning)
* The loops are independently steerable via their handles

## Manager inventory

| Manager               | `ask`                                          | `update`                               | `execute`                         | What it owns                            |
| --------------------- | ---------------------------------------------- | -------------------------------------- | --------------------------------- | --------------------------------------- |
| **ContactManager**    | Who people are, relationships, contact details | Create, edit, delete, merge contacts   | —                                 | People                                  |
| **KnowledgeManager**  | Domain facts, structured knowledge             | Create, change facts; refactor schemas | —                                 | What the assistant knows                |
| **TaskScheduler**     | Task status, queue state                       | Create, edit, reorder tasks            | Start tasks (returns live handle) | What the assistant needs to do          |
| **TranscriptManager** | Conversation history, search, analysis         | —                                      | —                                 | What was said                           |
| **GuidanceManager**   | Procedures, SOPs, strategies                   | Add, edit, delete guidance             | —                                 | How to do things                        |
| **FileManager**       | File metadata, parsing, content questions      | —                                      | —                                 | Received files                          |
| **WebSearcher**       | Web search, crawl, extract                     | —                                      | —                                 | The public internet                     |
| **SecretManager**     | Secret metadata (not values)                   | Store, edit, delete secrets            | —                                 | API keys, tokens                        |
| **MemoryManager**     | —                                              | —                                      | —                                 | Offline consolidation (not interactive) |

## Where to start reading

| File                                            | What's there                                     |
| ----------------------------------------------- | ------------------------------------------------ |
| `unity/contact_manager/base.py`                 | Example base class contract                      |
| `unity/common/state_managers.py`                | `BaseStateManager` with caller context injection |
| `unity/actor/environments/state_managers.py`    | How primitives are assembled                     |
| `unity/function_manager/primitives/registry.py` | The typed `Primitives` API surface               |