StatePlane

Getting Started

Prerequisites

• Python 3.13
• uv

StatePlane uses uv for dependency management, virtual environments, and local commands.

Install the Workspace

uv sync --all-packages --all-groups --python 3.13

Run the Core Quality Gates

uv run --all-packages --all-groups --python 3.13 ruff format --check .
uv run --all-packages --all-groups --python 3.13 ruff check .
uv run --all-packages --all-groups --python 3.13 mypy packages services tests examples
uv run --all-packages --all-groups --python 3.13 pyright
uv run --all-packages --all-groups --python 3.13 mkdocs build --strict
uv run --all-packages --all-groups --python 3.13 pytest tests/unit tests/integration --cov=packages --cov=services --cov-report=term-missing --cov-fail-under=95

Run the OpenAI Context Demo

Dry-run mode builds and renders the request without calling a provider:

uv run --all-packages --all-groups --python 3.13 python examples/openai_context_demo/demo.py

JSON output:

uv run --all-packages --all-groups --python 3.13 python examples/openai_context_demo/demo.py --format json

Live mode sends the compiled request to OpenAI:

OPENAI_API_KEY=... uv run --all-packages --all-groups --python 3.13 python examples/openai_context_demo/demo.py --live

Serve the Documentation Locally

uv run --all-packages --all-groups --python 3.13 mkdocs serve

The generated site is written to site/ during mkdocs build.

GitHub Pages

The repository includes a GitHub Pages workflow in .github/workflows/docs.yml.

To finish setup in GitHub:

1. Open the repository settings.
2. Go to Pages.
3. Set the source to GitHub Actions.

After that, pushes to main will build and deploy the site automatically.