duct-tape2/ai-language-partner

backend: add provider-status example response to docs

Open

#19 opened on Jul 8, 2026

View on GitHub
 (4 comments) (0 reactions) (1 assignee)TypeScript (2 forks)auto 404
backendclaimeddocsgood first issue

Repository metrics

Stars
 (2 stars)
PR merge metrics
 (PR metrics pending)

Description

Goal

Document three representative /v1/providers/status response excerpts so a contributor can understand the local-first provider boundary without configuring paid APIs or local speech engines.

Scope

  • Edit only docs/backend/API_RUNBOOK.md.
  • Add a short provider-status subsection near the existing quick check or Provider adapters section.
  • Include three trimmed JSON examples:
    1. Default mock mode: mode: "mock_open_core" with providers.llm, providers.tts, and providers.stt showing active: "mock", externalConfigured: false, and replaceable: true.
    2. Fallback mode: operations.rateLimit showing backend: "memory", requestedBackend: "redis", and an illustrative fallbackReason when Redis was requested but unavailable.
    3. Local speech engines: providers.tts showing active: "voicevox_compat" with its engine and fallback, plus providers.stt showing active: "whisper_cpp" and its boolean readiness fields.
  • Keep examples intentionally trimmed. /v1/providers/status also reports broader auth/content/experiment capabilities; this issue does not need to reproduce the entire payload.
  • Use apps/api/app/main.py, apps/api/app/providers.py, and apps/api/app/rate_limit.py only as sources of truth. Do not edit production code for this issue.
  • Use placeholders for machine-specific paths, exception classes, and base URLs. Never include a real API key, token, private host, or local user path.

Acceptance Criteria

  • All three labeled examples are present and valid JSON after replacing explanatory placeholders with JSON strings.
  • Field names and nesting match the current implementation.
  • The surrounding text explains that externalApiKeysRequired is false and that fallback status is diagnostic rather than proof that a live external engine succeeded.
  • The change stays within docs/backend/API_RUNBOOK.md.
  • The PR body includes Closes #19.

Suggested Verification

This is a browser-editable docs task; no backend or speech-engine installation is required.

python3 scripts/check_public_tree.py
git diff --check

Direct edit link: https://github.com/duct-tape2/ai-language-partner/edit/main/docs/backend/API_RUNBOOK.md

Contributor guide