Metadata-Version: 2.4
Name: pydantic-work
Version: 0.1.10
Summary: A local-first chat UI for Pydantic AI agents
Author-email: David Sanchez <64162682+dsfaccini@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/dsfaccini/ai-chat-ui/tree/pydantic-work
Project-URL: Repository, https://github.com/dsfaccini/ai-chat-ui/tree/pydantic-work
Project-URL: Issues, https://github.com/dsfaccini/ai-chat-ui/tree/pydantic-work/issues
Project-URL: Twitter, https://x.com/dasfacc
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: bs4>=0.0.2
Requires-Dist: fastapi>=0.117.1
Requires-Dist: httpx>=0.27.0
Requires-Dist: lancedb>=0.25.0
Requires-Dist: langchain-text-splitters>=0.3.11
Requires-Dist: logfire[fastapi]>=4.9.0
Requires-Dist: markdown2>=2.5.4
Requires-Dist: pip>=25.2
Requires-Dist: pydantic-ai-slim[anthropic,cli,google,openai]>=1.0.10
Requires-Dist: pyright>=1.1.405
Requires-Dist: python-frontmatter>=1.1.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: sentence-transformers>=5.1.1
Requires-Dist: sse-starlette>=3.0.2
Requires-Dist: starlette>=0.48.0
Requires-Dist: uvicorn>=0.37.0
Requires-Dist: watchfiles>=1.1.0

# Pydantic Chat

A local-first chat UI for your [Pydantic AI](https://ai.pydantic.dev/) agents.

```bash
uvx pydantic-work <module>:<agent variable>

# e.g. uvx pydantic-work src.my_agent:agent
```

## What is it?

Pydantic Chat provides a beautiful web interface for interacting with your Pydantic AI agents. Your agent runs locally on your machine, and the chat UI can be accessed either via localhost or through a secure remote URL.

**Important**: your messages never leave your machine and never touch the internet. Remote URLs are a convenience for you to run multiple agents on your machine without picking and keeping track of ports. Anyone visiting one of your URLs will get an empty chat window and a message like below &darr;

<img width="445" height="121" alt="image" src="https://github.com/user-attachments/assets/a97c0bfa-abda-46a9-a8c2-6a6c43ab2493" />

## Installation

```bash
# Install with uv
uv tool install pydantic-work

# Or install in development mode
cd agent
uv pip install -e ".[cli]"
```

## Usage

```bash
# Basic usage
pydantic-work module.path:agent_variable

# Example
pydantic-work src.golden_gate_bridge:agent

# Localhost-only mode (skip remote registration)
pydantic-work --localhost src.golden_gate_bridge:agent

# Custom port
pydantic-work --port 8000 src.golden_gate_bridge:agent
```

## How It Works

1. **Local Server:** Your agent runs on your machine with a FastAPI server
2. **Remote Access (Optional):** On first run, you'll be prompted to choose a project slug (e.g., `my-project`)
3. **Two URLs:** Access your chat via:
   - Local: `http://127.0.0.1:PORT`
   - Remote: `https://your-project.pydantic.work/` (if registered)

Your agent code and data never leave your machine. The remote URL just provides the frontend.

> **Note:** The localhost UI is served via CDN (jsdelivr) at a pinned version, while the remote UI is served from the Cloudflare Worker and may be on a different version. Both UIs are compatible with the same backend API.

## Example Agent

```python
# src/my_agent.py
from pydantic_ai import Agent

agent = Agent(
    'anthropic:claude-sonnet-4-0',
    instructions="You are a helpful assistant."
)

@agent.tool_plain
def get_current_time() -> str:
    """Get the current time."""
    from datetime import datetime
    return datetime.now().strftime("%I:%M %p")
```

Run it:

```bash
pydantic-work src.my_agent:agent
```

## Configuration

On first run, Pydantic Chat creates `.pydantic-work/config.json` in your project directory with your slug, token, and port. This folder is automatically added to `.gitignore`.

## Patterns

### Multiple Projects

Each project directory gets its own config, so you can run multiple agents with different slugs:

```bash
cd project-a && pydantic-work agent:agent  # -> project-a.pydantic.work
cd project-b && pydantic-work agent:agent  # -> project-b.pydantic.work
```

## Troubleshooting

**Failed to load agent:** Check that your module path is correct (`module.path:variable_name`).

**Registration failed:** The server will automatically fall back to localhost mode. Use `--localhost` to skip registration entirely.

**Slug already taken:** Choose a different slug when prompted. Slugs are globally unique.

## Links

- [Pydantic AI Documentation](https://ai.pydantic.dev/)
- [Pydantic](https://docs.pydantic.dev/)
