Skip to main content

API Reference

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/agent-platform-feedback-contract​

  • Purpose: publish the bounded Dobby-owned recommendation-only feedback and iteration-loop contract
  • Input: none
  • Output: JSON from ../contracts/agent_platform_feedback_iteration_lane_v1.json (contracts/agent_platform_feedback_iteration_lane_v1.json)
  • Important boundary:
    • Fabric remains canonical owner of maturity posture
    • Dobby publishes only its own advisory/materialization contract

GET /api/v1/learning/agent-platform-feedback-readback​

  • Purpose: materialize advisory-only feedback and iteration-loop posture from Fabric-owned maturity truth
  • Input: none
  • Output:
    • available
    • state
    • service_mode
    • signal_posture
    • target_layer_key
    • open_readbacks
    • stale_projection_status
    • fabric_maturity_payload
  • Fail / degraded semantics:
    • returns missing_context with fabric_agent_platform_feedback_truth_unavailable if canonical Fabric truth cannot be resolved
  • may return degraded when Fabric alignment drift is visible
  • never upgrades Dobby into gate, approval, or closeout authority

GET /api/v1/learning/weft-classification-feedback-contract​

  • Purpose: publish the bounded Dobby-owned recommendation-only contract for human-corrected Weft classification and candidate-binding outcomes
  • Input: none
  • Output: JSON from ../contracts/weft_classification_feedback_contract_v1.json (contracts/weft_classification_feedback_contract_v1.json)
  • Important boundary:
    • Weft remains the source of candidate and correction-signal posture
    • Fabric remains the source of data-classification posture
    • Dobby publishes only its own advisory learning contract

GET /api/v1/learning/weft-classification-feedback-readback​

  • Purpose: materialize advisory-only learning posture for bounded Weft classification feedback
  • Input: none
  • Output:
    • available
    • state
    • service_mode
    • signal_posture
    • feedback_events
    • required_fields
    • source_truth_payload
    • open_readbacks
    • stale_projection_status
  • Fail / degraded semantics:
    • returns missing_context with weft_classification_feedback_truth_unavailable if canonical Weft or Fabric truth cannot be resolved
    • may return degraded when Fabric alignment drift is visible
    • never upgrades Dobby into business-truth, closeout, or record authority

GET /api/v1/learning/crm-recommendation-signal-contract​

  • Purpose: publish the bounded Dobby-owned recommendation-only contract for CRM signal consumption and customization exception advisories
  • Input: none
  • Output: JSON from ../contracts/crm_recommendation_signal_contract_v1.json (contracts/crm_recommendation_signal_contract_v1.json)

GET /api/v1/learning/crm-recommendation-signal-readback​

  • Purpose: materialize advisory-only learning posture for bounded CRM recommendation signals and repeated customization exception patterns
  • Input: none
  • Output:
    • available
    • state
    • service_mode
    • signal_posture
    • allowed_inputs
    • required_fields
    • source_truth_payload
    • open_readbacks
    • stale_projection_status
  • Fail / degraded semantics:
    • returns missing_context with crm_recommendation_signal_truth_unavailable if canonical Spindle or Fabric truth cannot be resolved
    • may return degraded when Fabric alignment drift is visible
    • never upgrades Dobby into CRM, ERP, approval, or customization truth authority

GET /api/v1/learning/semantic-context-knowledge-contract​

  • Purpose: publish the bounded Dobby-owned recommendation-only contract for semantic context, source, budget, ontology, and knowledge-pack improvement proposals
  • Input: none
  • Output: JSON from ../contracts/semantic_context_knowledge_improvement_contract_v1.json (contracts/semantic_context_knowledge_improvement_contract_v1.json)
  • Important boundary:
    • Fabric remains the source of admission, activation, and semantic-plan truth
    • Bobbin remains the source of semantic projection and context-assembly truth
    • Dobby publishes only its own advisory improvement contract

GET /api/v1/learning/semantic-context-knowledge-readback​

  • Purpose: materialize advisory-only learning posture for bounded semantic context and knowledge-improvement proposals
  • Input: none
  • Output:
    • available
    • state
    • service_mode
    • signal_posture
    • proposal_classes
    • required_controls
    • forbidden_authorities
    • owner_boundaries
    • source_truth_payload
    • open_readbacks
    • stale_projection_status
  • Fail / degraded semantics:
    • returns missing_context with semantic_context_knowledge_improvement_truth_unavailable if canonical Fabric semantic-plan truth cannot be resolved
    • may return degraded when Fabric alignment drift is visible
    • never upgrades Dobby into truth, admission, activation, or context-delivery authority

GET /api/v1/learning/readiness​

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

GET /api/v1/learning/promotion-state-machine-contract​

  • Purpose: publish the Dobby-owned promotion state machine as a versioned contract for Fabric, Warp, and Pattern consumers
  • Output: contracts/promotion_state_machine_contract_v1.json
  • Authority semantics:
    • Dobby owns proposal lifecycle state and recommendation-only learning posture
    • Fabric remains contract-family admission and gate truth
    • Warp remains approval truth owner
    • Pattern remains work-item and wave truth owner
  • Fail / degraded semantics:
    • consumers must fail closed when this contract is missing or does not validate

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 as Prometheus text exposition
  • Media type: text/plain
  • Format: one sample per line as metric_name value or metric_name{label="value"} value
  • Output:
    • adaptive-learning counters and gauges
    • dobby_service_mode
    • dobby_persistence_ready
    • dobby_metrics_degraded when applicable
    • logical queue gauges such as dobby_queue_depth_intake, dobby_queue_depth_replay, and dobby_queue_depth_promotion
    • budget gauges such as dobby_replay_budget_remaining and dobby_promotion_velocity_remaining
  • Fail / degraded semantics:
    • Persistence unavailable still returns HTTP 200 with bounded degraded metrics
    • degraded output includes dobby_persistence_ready 0 and dobby_metrics_degraded 1
    • does not invent values from any shadow truth
    • queue depth metrics are logical runtime indicators, not a broker queue view

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.