Metadata-Version: 2.5
Name: alpha-avatar-agents
Version: 0.6.8
Summary: Transport-neutral Agent contracts and runtime composition for AlphaAvatar.
Project-URL: Source, https://github.com/AlphaAvatar/AlphaAvatar
Project-URL: Issues, https://github.com/AlphaAvatar/AlphaAvatar/issues
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: AI,agents,audio,llm,omni,realtime,video
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.14,>=3.13
Requires-Dist: alpha-avatar-core
Requires-Dist: filelock>=3.12
Requires-Dist: huggingface-hub>=0.25
Requires-Dist: jsonschema<5,>=4.18
Requires-Dist: langchain-community
Requires-Dist: langchain-core
Requires-Dist: livekit-blingfire~=1.0
Requires-Dist: markdown
Requires-Dist: mcp<2,>=1.10.0
Requires-Dist: omegaconf
Requires-Dist: pydantic<3,>=2
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: python-slugify
Requires-Dist: referencing<1,>=0.30
Requires-Dist: weasyprint
Provides-Extra: vdb
Requires-Dist: lancedb==0.30.2; extra == 'vdb'
Requires-Dist: langchain-qdrant; extra == 'vdb'
Requires-Dist: qdrant-client; extra == 'vdb'
Description-Content-Type: text/markdown

# AlphaAvatar Agents

`alpha-avatar-agents` defines Agent execution contracts and runtime composition.
Concrete model backends and feature implementations live in plugin packages;
application hosting and transport assembly belong to Host and RTC.

## 📦 Package structure

```text
alphaavatar/agents/
├── avatar/               # Engine, Loop, Context and Provider contracts.
├── runtime/              # Runtime composition, capability registry and inference.
├── configs/              # Strict Avatar and plugin-selection configuration.
├── character/            # Presentation and transport contracts.
├── memory/               # Memory interfaces and public schemas.
├── persona/              # Persona interfaces and public schemas.
├── router/               # Interaction processor contracts.
├── status/               # Status contracts.
├── tools/                # Tool abstractions and operation contracts.
├── reflection/           # Reflection contracts; not a completed feature.
├── utils/                # Workspace, identity, time and shared utilities.
├── env.py                # Environment initialization.
├── log.py                # Agent logging configuration.
└── version.py            # Package version.
```

Selected files and feature directories are shown; ordinary package initializers are omitted.

## Native execution

```text
Router turn decision / direct input
    -> AvatarEngine
    -> Foundation Loop
    -> ContextManager + ProviderService + CapabilityRegistry
    -> OutputRuntime
```

AvatarEngine owns bounded Turn admission, duplicate/stale-input isolation, submission
and precise interruption. It does not inherit a LiveKit Agent, construct model prompts,
register SDK tools or write directly to Memory.

Loop owns model/tool execution and canonical record publication. ContextManager owns
bounded history and query preparation. Provider owns model clients and tracing. State
and static loop budgets are captured once per query, not rewritten between model steps.
Generation completion remains distinct from playback completion and interruption.

## Ownership

Provider schemas, enums and abstractions are in `alphaavatar.agents.avatar.provider`.
Plugin implementations must not introduce SDK types into Core or public output data.
Runtime components use Core LifecycleComponent and LifecycleGroup where appropriate.
AvatarRuntime composes Session, State, Core runtimes, Foundation, capabilities and its
inference client; it is not the plugin lifecycle manager.

Engine starts its consumers before Router enables decisions. It stops admission and
settles Loop execution while its canonical record consumers still exist. Plugin
finalization remains in each plugin. Host owns the surrounding execution lifecycle;
transport detachment releases RTC subscriptions independently of Engine destruction.

InferenceRuntime owns the shared endpoint and serial runner processes. InferenceExecutor
owns only client connections. Host supervises the service but does not create a second
owner for runner processes. Neither failed jobs nor state-changing requests are
replayed automatically by the Host.

## Configuration

Agent configuration selects plugins and processor-owned `init_config` settings. The
main model is `loop.init_config.model`; there is no SDK `llm` section. Tool registration
does not grant approval: exact capability policy or an Engine authorizer is required.
The native provider extras are selected on `alpha-avatar-plugins-provider`, not on an
Agents SDK `providers` extra.

Host loads the shared application file and removes `host` before strictly validating
AvatarConfig. Execution children restore a validated snapshot, retaining the original
Avatar identity and resolved workspace rather than appending the Avatar ID again.
The `alphaavatar` command and its argument parser belong exclusively to Host.

## Boundaries

Native TTS and Character use AlphaAvatar contracts, not AgentSession. Host supplies
Character's scoped RTC transport, and the Character plugin owns browser presentation.
Real renderer, RTC and provider integration still require end-to-end validation.

Session-scoped Perception/Output consistency checks remain unchanged. Persistent
Episodes, cross-attachment recovery, sleep/wake and Dream scheduling are separate work.
