Build an analyzer

An analyzer is an HTTP service that reads a local segment and returns JSON. Its internal implementation can change while the surrounding orchestration and transport remain stable, provided it preserves the expected contract.

Start with a working example

Review the blink service and container template.

Create a uniquely named directory under healthcam-agent/services/. Include the analysis code, dependency specification, service entry point, container configuration when needed, and a manifest.

The generic template currently accepts video_path, but the orchestrator sends videopath. Align that request field before using the template. Also add the /status endpoint used by service monitoring.

Implement the HTTP boundary

The orchestrator calls POST /analyze with a shared container-local path:

{
  "videopath": "/workspace/segments/20260929120000.mkv"
}

Read the file and return a JSON-serializable result. The orchestrator wraps that response in a common envelope containing the analyzer ID, processing timestamp, input ID, filename, and success/error status.

Expose /health for dependency readiness and /status for runtime state. Distinguish successful processing with no usable signal from a real metric of zero. The blink service demonstrates this with visibility checks and explicit no-result reasons.

Declare and register the service

Use an existing manifest as the full reference. The following fields illustrate the key parts, but are not a complete installable manifest:

{
  "name": "my-analyzer",
  "runtime": { "type": "container" },
  "capabilities": ["analyzer"],
  "ports": { "http": { "default": 8040 } }
}

Define lifecycle commands for install, boot, and shutdown. Use the provided path placeholders and runtime environment variables rather than machine-specific absolute paths. Mount the segment directory at /workspace/segments and join the healthcam network.

Add your service ID to config.services.json and enable it. Restart the booter so it installs/launches the service and regenerates the registry. The orchestrator discovers enabled registry entries by capability; dropping a folder into services/ alone does not enable it.

Connect results to the product

The generic ingestion envelope accepts analyzer-specific data, but new metrics do not automatically produce dashboards.

For a new capability, implement the necessary data validation, transformation SQL, catalogue records, and UI. A new dashboard needs a definition in lib/dashboards.ts and a component mapping in app/(protected)/dashboards/[slug]/page.tsx, as well as its database catalogue entry.

The existing BPM transformation reads a specific analyzer ID. Replacing that implementation under the same output contract can preserve the pipeline; changing the ID or data shape requires updating its consumers.

Verify the extension

First test the analyzer independently with a known local video file. Confirm valid JSON, missing-file behavior, unavailable dependencies, and no-signal results. Then run it through the full agent test, initially with other optional analyzers disabled.

Check processing time against segment duration and inspect quality fields. An analyzer that is slower than incoming capture can create a growing backlog. The current platform does not provide bounded queues or automatic backpressure, so monitor disk use during experiments.