Getting started
What can be checked out, started, and verified today
An honest path through the currently supported surfaces. There is no installer and no released package; this is a development checkout.
What to expect
Three outcomes are reachable. Everything else on this site is still a design.
- A validated checkout. Tests, linters, type checks, and the migration drift check all run.
- A running HTTP service. Granian serves the Falcon application with the canonical REST surface and health endpoints.
- A local Kubernetes preview. The same image and chart the hosting contract describes, running in k3d.
Prerequisites
Four, and the Python version is not negotiable.
| Requirement | Why |
|---|---|
| Python 3.14 or later | The package uses language features from 3.14 and declares that floor. |
| uv | Resolves and installs the locked dependency set. |
| Make | Every gate is a Make target; running the underlying commands directly skips setup steps. |
| Docker | Needed for the container and local Kubernetes work. Container smoke tests are opt-in. |
A reachable PostgreSQL instance is also required before the service will pass its readiness check, since readiness is a database check.
Commands
Grouped by what they exercise. All are Make targets from the Episodic repository.
Prepare the checkout Available
uv sync- Install dependencies. Requires Python 3.14 or later.
make build- Build the virtual environment and install dependencies.
Validate the checkout Available
make test- Run the pytest suite, including behavioural scenarios and CrossHair contract checks.
make lint- Run linters, including the hexagonal import-boundary check.
make typecheck- Type-check the package.
make check-migrations- Detect schema drift between the models and the Alembic migrations.
Run the service Available
granian episodic.api.runtime:create_app_from_env --interface asgi --factory --host 0.0.0.0 --port 8080- Start the HTTP service. DATABASE_URL must be set.
curl -s localhost:8080/health/live- Confirm the process has booted.
curl -s localhost:8080/health/ready- Confirm infrastructure readiness. Returns 503 when the database check fails.
Exercise the hosting contract locally Available
make local-k8s-up- Create or update the local k3d preview.
make local-k8s-status- Inspect the local preview.
make local-k8s-logs- Show logs from the local preview.
make local-k8s-down- Tear the local preview down.
Container smoke tests are skipped unless
EPISODIC_RUN_DOCKER_TESTS=1 is set, because an agent or CI
environment may have no Docker daemon.
Confirming the service runs
Two endpoints, and they mean different things.
$ curl -i localhost:8080/health/live
HTTP/1.1 200 OK
$ curl -i localhost:8080/health/ready
HTTP/1.1 200 OK
$ # With no reachable database:
$ curl -i localhost:8080/health/ready
HTTP/1.1 503 Service Unavailable
Liveness reports only that the process booted. Readiness reports whether the infrastructure it depends on is reachable, which is why a 503 there is the expected answer rather than a fault - it tells an orchestrator to withhold traffic instead of restarting the container.
Confusing the two is the usual cause of a restart loop: a liveness probe pointed at the readiness endpoint will kill a healthy process every time its database blips.
Where this stops
The boundary between a running service and a usable product.
With the service running, the implemented REST surface is available: series profiles, episode templates, reference documents and bindings, and source intake. Generation can be driven for a draft without quality assurance. Nothing renders audio, and nothing offers an approval step.
See the endpoints available · Exercise the hosting contract · Read the developers' guide