victormerk/planpilot-service

Purpose and entry points

This is a containerized Python HTTP service for IPEXCO that exposes stateful PlanPilot planning sessions over /api. The process entry point is run.py; request handlers live in app/rest/sessions.py and app/rest/auth.py. Docker deployment is defined by Dockerfile.

HTTP boundary and authentication

The REST layer provides health/readiness/capabilities plus session operations. Authorization is enforced for protected routes using a bearer API key, while health and readiness remain unauthenticated. API inputs are converted into service-level session contracts at app/rest/sessions.py and app/service/session_contract.py; this is the boundary between untrusted HTTP data and planning execution.

Session lifecycle and capacity control

A session represents a prepared PDDL task plus a live FASB process whose selected facets persist until explicit stop or TTL expiry. app/service/session_registry.py owns active-session tracking, expiration, and admission limits. app/service/planpilot_service.py orchestrates session creation, facet queries/selections, and shutdown. This in-process registry is the primary state store and makes session continuity instance-local.

Planning pipeline

Session preparation accepts PDDL domain/problem material, parses or hashes it, and invokes Fast Downward to produce the planning representation required by PlanPilot. app/service/fastdownward_service.py encapsulates the subprocess boundary and timeout handling; app/utils/parsing.py and app/utils/hashing.py support validation/identity. The vendored Fast Downward driver performs translation and search: lib/downward/fast-downward.py, lib/downward/src/translate/translate.py, and lib/downward/src/search/planner.cc.

PlanPilot/FASB execution

The PlanPilot adapter starts and communicates with the bundled Linux x86_64 FASB executable, maintaining an interactive solver process per session. Core upstream assets are lib/planpilot/planpilot.py, lib/planpilot/bin/fasb, and lib/planpilot/scripts/facet-reason.fasb. PlanPilot includes ASP encodings for sequential horizons and facets in lib/planpilot/encodings/. This is a process and platform boundary: production images must be Linux amd64 or emulate it.

Persistence model

Persistence is isolated behind app/persistence/db.py and app/persistence/models.py. Its role is distinct from the active registry: durable records, if used, should not be assumed to contain live solver state. Session-facing orchestration should preserve this separation so database failures or restarts do not leave orphaned subprocesses.

Runtime and operational limits

The service runs in Docker and depends on Python plus vendored Python, C++, and native solver components. Configuration is environment-driven for API access, horizon, active-session cap, session TTL, and Fast Downward/FASB/query timeouts. CI builds through .github/workflows/build.yml. External network services are not indicated; the material external dependencies are local subprocesses and bundled planner binaries.