Metadata-Version: 2.4
Name: sayou-pydantic-ai
Version: 0.1.0
Summary: Sayou workspace toolset for Pydantic AI agents — persistent memory, file storage, and search
Project-URL: Homepage, https://github.com/pixell-global/sayou-pydantic-ai
Project-URL: Repository, https://github.com/pixell-global/sayou-pydantic-ai
Project-URL: Documentation, https://github.com/pixell-global/sayou-pydantic-ai#readme
Project-URL: Issues, https://github.com/pixell-global/sayou-pydantic-ai/issues
Author-email: Pixell <kevin_yum@pixell.global>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,llm,mcp,memory,persistence,pydantic-ai,sayou,toolset,workspace
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pydantic-ai>=0.2.0
Requires-Dist: sayou>=0.2.2
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# sayou-pydantic-ai

Persistent memory and workspace storage for [Pydantic AI](https://ai.pydantic.dev) agents. Write files, search content, and persist conversation history — all through a single toolset.

Built on [sayou](https://github.com/pixell-global/sayou), the file-system inspired context store for AI agents.

## Install

```bash
pip install sayou-pydantic-ai
```

## Quick Start

```python
from pydantic_ai import Agent
from sayou_pydantic_ai import SayouToolset

agent = Agent("openai:gpt-4o", toolsets=[SayouToolset()])
result = await agent.run("Save a note about our meeting decisions")
```

Zero config. The agent gets 7 workspace tools and a local SQLite store at `~/.sayou/`. Files persist across sessions.

## Tools

| Tool | Description |
|------|-------------|
| `workspace_write` | Create or update files (supports YAML frontmatter) |
| `workspace_read` | Read files with token budget control |
| `workspace_list` | List files and subfolders |
| `workspace_search` | Full-text and metadata search |
| `workspace_grep` | Content search with line context |
| `workspace_glob` | Pattern matching (`**/*.md`, `docs/**`) |
| `workspace_kv` | Key-value store for config/state |

### Optional tools (opt-in)

| Tool | Description |
|------|-------------|
| `workspace_delete` | Soft-delete files |
| `workspace_history` | Version history |
| `workspace_links` | File-to-file links |
| `workspace_chunks` | Chunk-based file reading |

Enable them with the `tools` parameter:

```python
from sayou_pydantic_ai.toolset import ALL_TOOLS

SayouToolset(tools=ALL_TOOLS)                          # Everything
SayouToolset(tools={"read", "write", "search", "delete"})  # Pick what you need
```

## Persist Conversation History

```python
from sayou.workspace import Workspace
from sayou_pydantic_ai import SayouToolset, SayouMessageHistory

async with Workspace() as ws:
    history = SayouMessageHistory(ws, conversation_id="project-alpha")
    agent = Agent("openai:gpt-4o", toolsets=[SayouToolset(workspace=ws)])

    # Load previous messages
    messages = await history.load()

    # Run with history
    result = await agent.run("Continue our discussion", message_history=messages)

    # Save for next session
    await history.save(result.all_messages())
```

Options:
- `max_messages=50` — keep only the last N messages
- `ttl_seconds=86400` — auto-expire after 24 hours

## Choose Your Tools

```python
# Default: 7 core tools
SayouToolset()

# Minimal: just read and write
SayouToolset(tools={"read", "write"})

# Full: all 11 tools including delete
SayouToolset(tools=ALL_TOOLS)

# Custom prefix
SayouToolset(tool_prefix="ws")      # ws_read, ws_write, ...
SayouToolset(tool_prefix="")        # read, write, ... (no prefix)
```

## Dependency Injection

Use `from_deps` when the workspace comes from your agent's dependency system:

```python
from dataclasses import dataclass
from sayou.workspace import Workspace
from sayou_pydantic_ai import SayouToolset

@dataclass
class MyDeps:
    workspace: Workspace

agent = Agent(
    "openai:gpt-4o",
    deps_type=MyDeps,
    toolsets=[SayouToolset.from_deps(lambda d: d.workspace)],
)
```

## Configuration

### Database

By default, sayou uses SQLite at `~/.sayou/sayou.db`. For production, point to MySQL or any SQLAlchemy-compatible database:

```python
SayouToolset(database_url="mysql+aiomysql://user:pass@host/db")
```

Or set the environment variable:

```bash
export SAYOU_DATABASE_URL="mysql+aiomysql://user:pass@host/db"
```

### Workspace identity

```python
SayouToolset(
    workspace=Workspace(
        slug="my-project",
        org_id="my-org",
        user_id="agent-1",
    )
)
```

## How It Works

`SayouToolset` implements Pydantic AI's `AbstractToolset` interface. When the agent runs:

1. `get_tools()` returns tool definitions with JSON schemas
2. The LLM sees tools like `workspace_write(path, content)` and calls them
3. `call_tool()` dispatches to the corresponding `Workspace` method
4. Results are returned to the LLM as strings

Files are stored with version history. Every write creates a new version — nothing is lost.

`SayouMessageHistory` uses sayou's built-in KV store to serialize/deserialize Pydantic AI's `ModelMessage` objects via `TypeAdapter`.

## Links

- [sayou](https://github.com/pixell-global/sayou) — the workspace engine
- [Pydantic AI](https://ai.pydantic.dev) — the agent framework
- [Pydantic AI Toolsets](https://ai.pydantic.dev/toolsets/) — toolset documentation

## License

Apache 2.0
