Automation Core

This service is the platform control plane for deterministic service operations.

Responsibilities

• Start, stop, restart, and check readiness of platform services in dependency order.
• Validate startup sequencing and return structured operational state.
• Provide a compact, large-language-model-friendly API for orchestration tasks.
• Keep all automation verbs idempotent and return machine-friendly outputs.
• Enforce service manifest-driven startup contracts.

Dependencies

• Loads service definitions from config/service-manifest.json.
• Uses command configuration for all managed services.
• Exposes a runtime API for orchestrating and introspecting startup state.

Development

cd services/automation-core
uv sync
Copy

Use the repository bootstrap entrypoint to run this service:

uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py up --start-stack
uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py smoke --smoke-open-ui
Copy

Runtime / operations API

• GET / — service purpose and capabilities.
• GET /health — health check.
• GET /ready — readiness gate.
• GET /state — full state payload.
• GET /state/compact — compact table-style payload for LLM tooling.
• GET /services — service manifest and state.
• GET /services/{name} — one service detail.
• POST /services/{name}/start — transition one service to running.
• POST /services/{name}/stop — transition one service to stopped.
• POST /services/{name}/restart — restart one service.
• POST /orchestration/start-all — start all services in declared order.
• POST /orchestration/stop-all — stop all services in reverse order.
• GET /orchestration/topology — dependency graph.
• GET /startup/check-list — startup readiness checklist metadata.
• GET /ui — lightweight manual control panel.
• GET /contracts — structured machine-readable contract.
• GET /self-documentation.md and /self-documentation — generated operational instructions.
• GET /manifest — source-of-truth manifest snapshot.

Control-plane startup script

Use a single bootstrap entrypoint:

uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py up
uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py up --port 50001
uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py up --run-mode in-place
Copy

When --port is omitted, the script auto-allocates a free port from the configured pool and prints the allocated value. Use --run-mode fork (default, starts automation-core in a subprocess) or --run-mode in-place (runs it in the current process).

Smoke run:

uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py smoke --smoke-open-ui
Copy

Smoke mode starts the control plane, starts managed services, and runs a standard verification sweep (status, contracts, /state/compact) in one command.

Combined human + LLM test cycle

Recommended flow for a full end-to-end check:

uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py up --start-stack --port 50001
Copy

• Open http://127.0.0.1:50001/ui in a browser and verify the control panel loads.
• Run:

uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py status
uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py docs
Copy

• Verify:

• all expected services in /state and /state/compact,

• status: running for started services,

• no startup failures in uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py down output when shutting down.

Shutdown:

uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py down
Copy

Operator note (current behavior)

• uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py up --dry-run validates startup intentions without launching long-running processes.
• --port may be omitted for automatic assignment; when supplied and unavailable, startup returns a clear error.
• Manifest endpoints now support http://...:{port} placeholders, resolved at runtime and reflected in:
  • GET /manifest
  • GET /state
  • GET /state/compact
  • GET /contracts
• The launcher sets HOST and PORT for each managed service so each service can bind to its assigned port.

Contract references:

• documentation/contracts/automation-core.md
• GET /contracts
• GET /self-documentation.md

Useful companion commands:

• uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py up --start-stack
• uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py status
• uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py check
• uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py docs
• uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py down

Planned behavior

• Read and apply a service manifest (service list, startup order, dependencies, endpoints).
• Verify preconditions (DB availability, queue/API bindings, expected versions).
• Execute or delegate control actions through service managers (systemd, NSSM, scripts).
• Keep automation verbs deterministic and idempotent.

Health checks

• Automation readiness is controlled by this service's GET /ready and GET /health.
• Operational tooling should use /state for explicit status.
• Startup actions include health polling before returning success for managed services.