Metadata-Version: 2.4
Name: t4l-server
Version: 0.2.0
Summary: Self-hosted REST and MCP server for T4L Trainer agent workflows.
Project-URL: Homepage, https://github.com/BigSlikTobi/t4l-server
Project-URL: Repository, https://github.com/BigSlikTobi/t4l-server
Project-URL: Issues, https://github.com/BigSlikTobi/t4l-server/issues
Author: T4L Trainer
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: build>=1.3; extra == 'dev'
Requires-Dist: mypy>=1.18; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.14; extra == 'dev'
Requires-Dist: twine>=6.2; extra == 'dev'
Description-Content-Type: text/markdown

# T4L Server

Self-hosted REST and MCP server for exchanging T4L Trainer JSON artifacts
between the iPhone app and a coaching agent.

The phone remains the source of truth for accepted training state. The server
stores synced context and pending agent results in SQLite so local agents,
home-server agents, and private VPS agents can work through the same protocol.

## Install

```bash
pipx install t4l-server
t4l-server serve --data-dir ~/T4LServerData
```

The command prints the server URL, MCP URL, and API key. Enter the server URL
and API key in the T4L Trainer Settings screen. Pass `--log-level DEBUG` for
verbose request and error logging (logs go to stderr; the API key is only ever
printed to stdout on startup).

## Agent setup

Agents should read the public instruction repo first:

```text
https://github.com/BigSlikTobi/t4l-agent-instructions
```

Those instructions explain how to start or verify this server, connect through
MCP, wait for fresh phone context, and write app-consumed results safely.

## Safety model

- REST and MCP endpoints require the API key, compared in constant time.
- Request bodies over 25 MiB are rejected (413) to bound memory use.
- JSON artifacts are stored in `t4l.sqlite` (WAL mode; writes use an immediate
  transaction so concurrent upserts cannot interleave).
- Image blobs are stored under `blobs/`.
- Path traversal and arbitrary file access are rejected.
- Stored payloads are structurally validated before persisting.

## Architecture

Zero runtime dependencies by design — the server is built on the Python
standard library (`http.server`) so it installs and runs anywhere `pipx` does.
Keep it dependency-free.

- `constants.py`: single source of truth for artifact kinds, route maps, limits.
- `store.py`: SQLite artifact store (WAL, immediate-transaction upserts).
- `server.py`: REST handler, auth, body limits, logging.
- `mcp.py`: JSON-RPC MCP tools (read context / write results).
- `validation.py`: structural payload validation shared by REST + MCP writes.
- `cli.py`: `serve` entrypoint and logging configuration.

## Development

```bash
python -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
ruff format --check .
ruff check .
mypy
pytest
python -m build
twine check dist/*
```
