flightdeck-ai 1.0.1

AI Release Governance for production agents.

FlightDeck

FlightDeck is AI Release Governance for production agents.

It gives teams a local-first control loop for release safety: register immutable agent releases, ingest runtime evidence, compare trusted diffs, and gate promotion with policy.

FlightDeck is not an agent framework, prompt IDE, tracing dashboard, or gateway. It is the operating record for what changed, what it costs, how it behaves, and whether it is safe to promote.

Why It Exists

AI agent changes can silently alter cost, latency, failure rate, and unit economics. FlightDeck turns those changes into explicit release decisions backed by runtime evidence.

Current local spine:

• versioned release.yaml artifacts with bundle checksums
• RunEvent ingestion from JSONL or JSON arrays
• immutable pricing tables with explicit --replace
• trusted flightdeck release diff
• policy-gated flightdeck release promote
• promotion decision history

Status

FlightDeck is local-first and ships as a Python CLI backed by SQLite.

v1.0.0 establishes SemVer-stable public contracts for the documented CLI (docs/cli.md on main), committed schemas/v1/, and POST /v1/events with api_version v1. See RELEASE_NOTES.md and docs/spec-v1-forward.md. The product scope is still intentionally narrow (release governance, not a hosted agent platform).

Not implemented yet:

• hosted control plane
• automated traffic routing
• tool-cost pricing
• OpenTelemetry import/export mapping (optional uv sync --extra telemetry or pip install 'flightdeck-ai[telemetry]' for future work)

Shipped locally:

• flightdeck serve + POST /v1/events
• minimal Python SDK (flightdeck.sdk.client)
• flightdeck release rollback (policy-gated, audited)

Quickstart

Install uv, then from the repo root:

uv sync --extra dev
uv run flightdeck --help

Or with pip and a venv:

python -m venv .venv
python -m pip install -e ".[dev]"
flightdeck --help

Run the cross-platform quickstart smoke (same as CI):

uv run python scripts/quickstart_smoke.py

(or python scripts/quickstart_smoke.py inside an activated venv)

Or use the bash wrapper (Git Bash / WSL on Windows):

./scripts/smoke.sh

Or walk through the core commands:

flightdeck init
flightdeck pricing import examples/quickstart/pricing-baseline.yaml
flightdeck pricing import examples/quickstart/pricing-candidate.yaml
flightdeck policy set examples/quickstart/policy.yaml

BASELINE=$(flightdeck release register examples/quickstart/baseline-release)
CANDIDATE=$(flightdeck release register examples/quickstart/candidate-release)

sed "s/__BASELINE_RELEASE_ID__/${BASELINE}/g" examples/quickstart/baseline-events.jsonl > baseline-events.jsonl
sed "s/__CANDIDATE_RELEASE_ID__/${CANDIDATE}/g" examples/quickstart/candidate-events.jsonl > candidate-events.jsonl

flightdeck runs ingest baseline-events.jsonl
flightdeck runs ingest candidate-events.jsonl

flightdeck release diff "$BASELINE" "$CANDIDATE" --window 7d
flightdeck release promote "$BASELINE" --env local --window 7d --reason "initial baseline"
flightdeck release history --agent agent_support --env local

The static event files in examples/quickstart use placeholder release IDs so the repo can ship stable examples. Substitute them before ingestion, or run uv run python scripts/quickstart_smoke.py / python scripts/quickstart_smoke.py (venv) or ./scripts/smoke.sh from Git Bash/WSL on Windows.

Documentation

This tree stays small; narrative docs live on github.com/flightdeckdev/flightdeck (main):

• Quickstart
• CLI reference
• Architecture
• Specification (0.x snapshot)
• Forward spec — v1 GA track
• v1 next steps (backlog)
• JSON Schemas (in this repo)
• Changelog
• Release notes (maintainer)
• Roadmap
• Contributing
• CLAUDE.md (short agent entry; see AGENTS.md for full rules)
• Development
• Security
• Research clone vs org repos
• Git remotes: personal vs org
• GitHub org & push gate

Development

uv sync --frozen --extra dev
uv run python -m ruff check src tests
uv run python -m pytest

See DEVELOPMENT.md for uv and pip setup, verification, troubleshooting, and PyPI releases (tag-driven; not on merge to main).

License

FlightDeck is licensed under the Apache License, Version 2.0 — see LICENSE and NOTICE.

The canonical public repository: https://github.com/flightdeckdev/flightdeck.