Tris

Tris is a modular document intelligence service built with FastAPI.

This repository is currently at the project base stage: app shell, shared error handling, typed configuration, tests, and developer tooling are in place. The extractor module is planned as the next Phase 1 implementation.

Tech Stack

• Python 3.11+
• FastAPI + Uvicorn
• Pydantic / pydantic-settings
• uv (dependency and environment management)
• Ruff + Pyright + pytest

Quickstart

1) Install dependencies

uv sync

2) Configure environment

Create a .env file from .env.example and set your Gemini key:

• Required: GEMINI_API_KEY
• Optional defaults are already provided in src/config.py

3) Run the API

uv run uvicorn src.main:app --host 127.0.0.1 --port 8000 --reload

Health check:

curl http://127.0.0.1:8000/health

Expected response:

{"status":"ok","app":"tris"}

Development Commands

Run tests:

uv run pytest

Lint:

uv run ruff check src/ tests/

Format:

uv run ruff format src/ tests/

Type check:

uv run pyright src/

Install and run pre-commit hooks (requires a Git repository):

uv run pre-commit install
uv run pre-commit run --all-files

Docker

Build image:

docker build -t tris .

Run container:

docker run --rm -p 8000:8000 -e GEMINI_API_KEY=your_key tris

Project Layout

src/
  main.py              # FastAPI app factory and /health
  config.py            # typed settings
  dependencies.py      # app-wide dependencies
  common/
    exceptions.py      # shared exception hierarchy
    error_handlers.py  # shared error envelope handlers

tests/
  conftest.py
  test_health.py
  test_config.py
  test_error_handling.py

Documentation

This is a docs-first repository. Start here before making changes:

• docs/product-roadmap.md
• docs/documentation-standard.md
• docs/prd/project-base-prd.md
• docs/plan/project-base-plan.md
• AGENTS.md