Skip to main content

API

Documentation Map​

API And Endpoint Behavior

Tool / Contract Summary​

This page documents the actual FastAPI routes exposed by jhf-dobby. Route ownership lives in src/jhf_dobby/api/routes.py (src/jhf_dobby/api/routes.py). The API publishes Dobby-owned state and consumes Fabric/Warp/Shuttle truth through internal service layers.

Business Value​

  • gives operators and other stack services a stable runtime surface for adaptive-learning state
  • exposes degraded/fail-closed behavior explicitly instead of hiding failures
  • keeps route documentation aligned with the code and manifest

Current Verified State​

Available now:

  • all routes listed in fabric-manifest.json
  • live verification against the service on <internal-runtime-redacted>:18096
  • bounded degraded behavior for /ready and /metrics under persistence loss

Planned / not in current scope:

  • route-level auth enforcement inside the app
  • additional versioned API namespaces beyond /api/v1

Public Surfaces​

GET /health​

  • Purpose: low-cost liveness probe
  • Input: none
  • Output: {"status":"ok","service":"jhf-dobby"}
  • Degraded behavior: none; this route stays available even when other subsystems are unhealthy

GET /ready​

  • Purpose: service readiness summary
  • Input: none
  • Output:
    • overall status
    • effective service mode
    • Fabric alignment object
    • queue-depth view
    • backpressure flag
    • human-readable detail
  • Fail / degraded semantics:
    • returns degraded when Fabric is unavailable
    • returns degraded and forces warmup when persistence is unavailable
    • does not hang on bounded persistence failure

GET /version​

  • Purpose: expose repo runtime version and current mode
  • Input: none
  • Output: version string plus effective service mode

GET /fabric-manifest.json​

  • Purpose: publish repo/runtime metadata as shipped with the service
  • Input: none
  • Output: JSON manifest document from fabric-manifest.json (fabric-manifest.json)
  • Note: this is Dobby metadata, not Fabric governance truth

GET /api/v1/learning/contracts​

  • Purpose: publish Dobby's derived contract status
  • Input: none
  • Output:
    • service modes
    • promotion states
    • producer families
    • consumer families
    • invariants
    • no-learn zones
    • target types
  • Important boundary:
    • producer/consumer family values come from Fabric matrix consumption
    • Dobby does not define family truth locally

GET /api/v1/learning/readiness​

  • Purpose: versioned readiness surface for internal consumers
  • Input: none
  • Output: same readiness model as /ready

POST /api/v1/learning/signals/intake​

  • Purpose: ingest a trace into Dobby learning state
  • Important inputs:
    • tenant_ref
    • trace_id
    • correlation_id
    • outcome
    • guardrail_decision
    • family_version_set
  • Important outputs:
    • run_id
    • state
    • signal_emitted
    • run_hash
    • priority_score
    • provenance_hash
    • sampled_in
  • Fail / block semantics:
    • 422 on tenant inconsistency
    • 422 on BLOCK
    • 422 on security-critical traces

POST /api/v1/learning/replay/evaluate​

  • Purpose: evaluate a replay candidate against a threshold contract
  • Important inputs:
    • target type/id
    • threshold contract
    • baseline and candidate metrics
    • workload similarity flag
  • Important outputs:
    • replay_id
    • candidate_hash
    • provenance_hash
    • verdict
    • threshold pass flag
  • Fail / block semantics:
    • 422 on disabled weight_training_candidate
    • 422 on replay budget exhaustion

POST /api/v1/learning/replay/propose-from-evidence​

  • Purpose: bind a signal-emitting run record to a deterministic replay comparison and create a governed proposal in one owner-scoped loop
  • Important inputs:
    • run_id
    • target type/id
    • current_decision
    • candidate_decision
    • replay metrics and threshold contract
    • baseline validity window
  • Important outputs:
    • run_id
    • replay_id
    • proposal_id
    • replay candidate/provenance hashes
    • deterministic decision_delta_hash
    • resulting proposal state
  • Fail / block semantics:
    • 422 when the source run is missing or did not emit a signal
    • 422 when current and candidate decisions are identical
    • 422 when source evidence or baseline validity is stale
    • 422 when replay rejects the candidate
    • 503 when persistence is unavailable

POST /api/v1/learning/promotions/propose​

  • Purpose: create a promotion proposal from replay evidence
  • Important inputs:
    • service mode
    • risk class
    • replay verdict
    • no-learn/security flags
    • target info
  • Important outputs:
    • proposal_id
    • candidate/provenance hashes
    • proposal state
    • revalidate_required
    • oscillation_detected
  • Fail / block semantics:
    • 422 in warmup or observe_only
    • 422 on blocked target/risk combinations

POST /api/v1/learning/promotions/approve-check​

  • Purpose: bind a proposal to the canonical Warp approval lane
  • Important inputs:
    • proposal_id
    • approval_id
  • Important outputs:
    • proposal state after Warp evaluation
    • policy approval flag
    • human approval flag
    • stale invalidation flag
  • Fail / block semantics:
    • 422 if proposal does not exist or state transition is invalid
    • fail-closed when Warp is missing, stale, mismatched, or unavailable

POST /api/v1/learning/promotions/activate​

  • Purpose: activate a Dobby-owned runtime change
  • Important inputs:
    • proposal_id
    • activation idempotency key
  • Important outputs:
    • new proposal state
    • runtime_state_before
    • runtime_state_after
  • Fail / block semantics:
    • 422 if service mode is not effectively promotion_enabled
    • 422 if approvals are missing
    • 422 if a conflicting active candidate exists
    • 422 if the promotion velocity breaker is active

POST /api/v1/learning/promotions/rollback​

  • Purpose: roll back an activated proposal
  • Important inputs:
    • proposal_id
    • rollback idempotency key
    • reason
  • Important outputs:
    • final state
    • rollback_restored
  • Fail / block semantics:
    • 422 if the proposal is not currently activated

GET /api/v1/learning/runs/{run_id}​

  • Purpose: fetch durable run state
  • Output: stored run record view
  • Fail semantics: 404 if not found

GET /api/v1/learning/proposals/{proposal_id}​

  • Purpose: fetch durable proposal state
  • Output: stored proposal view
  • Fail semantics: 404 if not found

GET /metrics​

  • Purpose: export runtime counters and gauges
  • Output:
    • adaptive-learning counters and gauges
    • dobby_service_mode
    • dobby_persistence_ready
    • dobby_metrics_degraded when applicable
  • Fail / degraded semantics:
    • returns bounded degraded metrics output when persistence is unavailable
    • does not invent values from any shadow truth

Contract Families​

  • Consumer families come from Fabric matrix consumption
  • Producer families come from Fabric matrix consumption
  • Route consumers should treat /api/v1/learning/contracts as a derived view, not a source-of-truth contract registry

Known Limits​

  • no OpenAPI-specific handwritten guide in the repo
  • no dedicated auth middleware
  • no pagination or search routes for stored runs/proposals
  • jhf-dobby#30
  • jhf-dobby#31
  • jhf-dobby#32
  • jhf-dobby#36
  • jhf-dobby#48
  • jhf-dobby#46
  • jhf-dobby#49

License: AGPLv3. See ../LICENSE (LICENSE).
Learn more at helpifyr.com.