Metadata-Version: 2.4
Name: yuuagents
Version: 0.2.0
Summary: Agent runtime with SDK imports, bundled CLI, optional daemon bootstrap, and built-in tools
Keywords: agents,llm,runtime,cli,sdk
Author: Tomorrowdawn
Author-email: Tomorrowdawn <tomorrowdawn@mail.ustc.edu.cn>
License-Expression: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: yuutools>=0.1.0
Requires-Dist: yuullm>=0.7.0
Requires-Dist: yuutrace>=0.1.8
Requires-Dist: attrs>=24.2.0
Requires-Dist: msgspec>=0.19.0
Requires-Dist: aiosqlite>=0.21.0
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: starlette>=0.40.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: aiodocker>=0.23.0 ; extra == 'all'
Requires-Dist: tavily-python>=0.5.0 ; extra == 'all'
Requires-Dist: aiodocker>=0.23.0 ; extra == 'docker'
Requires-Dist: tavily-python>=0.5.0 ; extra == 'web'
Requires-Python: >=3.14
Provides-Extra: all
Provides-Extra: docker
Provides-Extra: web
Description-Content-Type: text/markdown

# yuuagents

A minimal Python agent runtime built around a single runtime core: `Flow`.

```
Flow = observable execution + mailbox + cancellation
Agent = LLM loop on top of Flow
Basin = live-flow index
TaskHost = SDK-first host API
```

## Architecture

`Flow` is the only runtime object that matters.

- `Flow` records what happened, owns a mailbox, tracks parent/children, and can be cancelled or waited on.
- `Agent` is the LLM executor attached to a root `Flow`.
- `Deferred` is a `Flow` state, not a separate object type.
- `Basin` indexes all live flows, not just roots.
- `TaskHost` is the host-facing API for submit, status, history, inspect, wait, cancel, and persistence.
- Daemon/CLI support is an adapter layer on top of `TaskHost`, not the core model.

## Persistence

SDK-only users should be able to run the runtime without `yagents install`.

- In-process persistence should work without any daemon or socket.
- Durable local persistence should be optional and pluggable.
- The daemon adapter may use default disk locations and discovery files, but those are deployment conveniences, not runtime requirements.

## Core Model

```
TaskHost
├── Basin
│   ├── flow lookup by id
│   ├── live flow registry
│   └── flow-level inspect / wait / cancel
└── Persistence
    ├── in-memory for SDK use
    └── optional disk-backed storage

Agent
├── root Flow
├── messages / usage / rounds
└── tool execution on child Flows
```

## Flow Semantics

`Flow` is the execution topology.

- Each flow has an `id`, `kind`, `info`, `stem`, `mailbox`, `children`, and optional parent link.
- `send(content)` accepts `str`, `Item`, or `list[Item]`.
- The meaning of `send` is flow-specific and follows dependency inversion: different flow kinds interpret the same content differently.
- A deferred flow continues running and may later notify its parent through the mailbox.

## Host API

`TaskHost` is the main service boundary for both SDK and daemon usage.

```python
host = TaskHost(basin=basin, persistence=persistence, root_factory=root_factory)

task_id = await host.submit(spec)
info = await host.status(task_id)
history = await host.history(task_id)
await host.wait(task_id)
await host.cancel(task_id)
```

This is the level that should remain stable. CLI and HTTP are projections of this API.

## Built-in Tool Families

- `delegate`: create a child agent flow through the host/runtime boundary.
- `execute_bash`: create an interactive terminal flow when Docker is available.
- `inspect_background`, `wait_background`, `cancel_background`, `input_background`, `defer_background`: host-level operations over live flow ids.
- `web_search`, `read_file`, `edit_file`, `delete_file`, `sleep`, `view_image`: ordinary tools that do not require host-level control.

## Design Notes

- Root flow id should be the task id.
- The implementation should prefer one truth source for runtime state, not mirrored host-side caches.
