Metadata-Version: 2.4
Name: lattis
Version: 0.4.0
Summary: A pluggable agent toolkit (server + TUI + web UI)
Project-URL: Homepage, https://github.com/caesarnine/lattis
Project-URL: Repository, https://github.com/caesarnine/lattis
Project-URL: Issues, https://github.com/caesarnine/lattis/issues
License-Expression: MIT
Keywords: agent,ai,automation,bash,cli,llm,tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.14
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: fastapi>=0.110.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: logfire>=3.0.0
Requires-Dist: pydantic-ai>=1.37.0
Requires-Dist: textual>=6.11.0
Requires-Dist: trafilatura>=2.0.0
Requires-Dist: uvicorn>=0.30.0
Provides-Extra: lint
Requires-Dist: ruff>=0.9.0; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# Lattis

Lattis is a pluggable agent toolkit built on **pydantic-ai**: a FastAPI server with a Textual TUI and a bundled web UI.
Agents are loaded as plugins, and each thread can select a different agent.

## What you get

- **Server + clients**: FastAPI API, Textual TUI, and a web UI (served by the same server).
- **Pluggable agents**: built-ins, third-party entry points, or local `module:attribute` specs.
- **Per-thread agent selection**: pick an agent per thread (TUI + web UI + API).
- **Persistent state**: thread history in SQLite, plus a workspace directory for agents that write files/tools.

## Requirements

- [uv](https://docs.astral.sh/uv/)
- Python 3.14+ (uv can install it automatically)
- An API key for at least one model provider (Gemini, Anthropic, OpenAI, etc.)

## Quick start

```bash
uv sync
uv run lattis
```

Run the server (API + web UI):

```bash
uv run lattis server
```

Then open `http://localhost:8000`.

## CLI

```bash
lattis                 # Run the TUI (default)
lattis tui             # Run the TUI explicitly
lattis server          # Run the API server (and web UI, if built)
```

### `lattis tui`

```
--server <url>          Connect to a specific server URL
--local                 Force local mode (skip server auto-discovery)
--agent <id|name>       Default agent for local/in-process mode
--agents <specs>        Extra plugins (comma-separated `module:attr` specs) for local/in-process mode
```

By default, the TUI auto-discovers a server on `http://127.0.0.1:8000` and connects if it matches the current project;
otherwise it runs in local (in-process) mode.

### `lattis server`

```
--host <host>           Host interface to bind (default: 127.0.0.1)
--port <port>           Port to bind (default: 8000)
--reload                Enable auto-reload
--workspace             Workspace mode: local | central
--agent <id|name>       Default agent id or name
--agents <specs>        Extra plugins (comma-separated `module:attr` specs)
```

## Agents

Built-in agents:

- `binsmith` — a script-building developer agent that can write reusable, composable tools
- `poetry` — a simple example agent

### Select an agent per thread

- **TUI**: use `/agent`, `/agent list`, `/agent set <id|number>`, `/agent default`
- **Web UI**: use the sidebar agent selector
- **API**: `PATCH /sessions/{session_id}/threads/{thread_id}/state` with `{"agent": "<id-or-name>"}` (or `null` to reset)

### Client integration

See `docs/client-integration.md` for the thin-client API flow (bootstrap, thread state, model options, streaming).

### Add your own agent plugins

Lattis discovers agents automatically from:

1. `lattis.agents.builtins` (included with Lattis)
2. Python entry points in the group **`lattis.agents`**
3. Extra `module:attribute` specs via `AGENT_PLUGINS` / `--agents`

Entry point example (`pyproject.toml` in your plugin package):

```toml
[project.entry-points."lattis.agents"]
my-agent = "my_package.my_agent:plugin"
```

Your `plugin` can be:

- an `AgentPlugin`, or
- a `pydantic_ai.Agent`, or
- a callable that returns an `Agent` (optionally taking `model`).

## Storage

Workspace modes:

- `local` (default): per-project `.lattis/` under the current directory
- `central`: `~/.lattis/`

Typical layout:

```
.lattis/
  lattis.db
  session_id
  workspace/
```

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `AGENT_DEFAULT` | `binsmith` | Default agent id/name (server + local mode) |
| `AGENT_PLUGINS` | *(unset)* | Extra plugins (`module:attr`, comma-separated) |
| `LATTIS_WORKSPACE_MODE` | `local` | `local` (per-project) or `central` (`~/.lattis`) |
| `LATTIS_SERVER_URL` | *(unset)* | Server URL for clients that connect over HTTP |
| `LATTIS_PROJECT_ROOT` | *(cwd)* | Project root used for `local` storage mode |
| `LATTIS_DATA_DIR` | *(derived)* | Override the data directory |
| `LATTIS_WORKSPACE_DIR` | *(derived)* | Override the workspace directory |
| `LATTIS_DB_PATH` | *(derived)* | Override the SQLite DB path |
| `LATTIS_SESSION_FILE` | *(derived)* | Override the session id file path |
| `LATTIS_SESSION_ID` | *(unset)* | Force a specific session id |

## Web UI development

The server serves the web UI from `lattis/web/static` when it exists.

```bash
cd frontend
npm install
npm run build
```
