Bonita Core API

A private internal FastAPI service that centralizes AI logic for Bonita-powered products.

What it is

Bonita Core API is the shared intelligence layer for:

• heyBonita.ai
• RSC Canvas (rsc_canvas)
• RSC LMS (rsc_lms)
• BLVX (blvx)

Apps call this service instead of talking to model providers directly. Responses should present Bonita—not vendor or model names.

Features

• Internal app authentication — per-product API keys (X-Bonita-App-Id, X-Bonita-App-Key)
• Layered Bonita persona system — base identity, app layer, institution context, profile tone, safety
• Task routing — task_type → behavior and defaults
• Role-based model routing — fast / default / heavy / deep / creative mapped to concrete model IDs via env
• CompactifAI provider adapter — OpenAI-compatible chat completions, retries, normalized usage
• Edge eligibility tagging — classifies tasks for future edge/offline use; v1 always executes on cloud
• Diagnostics and usage logging — structured logs; /v1/diagnostics for safe config checks (no secrets)

Project layout

app/
  main.py              # FastAPI app
  config.py            # Settings from environment
  api/routes/          # HTTP routes
  core/                # Auth, persona, routing, prompts, edge tags, usage
  providers/           # CompactifAI client
  models/              # Request/response schemas
  services/            # Orchestration
requirements.txt
.env.example

Run locally

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env: set COMPACTIFAI_API_KEY and BONITA_INTERNAL_APP_KEYS_JSON
uvicorn app.main:app --reload

Interactive API docs: http://127.0.0.1:8000/docs

Important

• Do not commit .env. It is gitignored; use .env.example as the template only.

Railway / production model env vars

Set DEFAULT_FAST_MODEL, DEFAULT_DEFAULT_MODEL, DEFAULT_HEAVY_MODEL, DEFAULT_DEEP_MODEL, and DEFAULT_CREATIVE_MODEL to model IDs your upstream (CompactifAI or an OpenAI-compatible endpoint) actually supports. If you use Groq, use current IDs from the Groq models list (for example llama-3.3-70b-versatile for a strong general model). A mistyped or retired ID causes provider errors (502) from Bonita Core.

Example endpoints

Method	Path	Notes
GET	/health	Liveness (no auth)
GET	/v1/diagnostics	Config presence checks (requires app headers)
POST	/v1/chat	Chat-style turn
POST	/v1/generate	Full generation pipeline

Authenticated routes expect:

• X-Bonita-App-Id: one of heybonita, rsc_canvas, rsc_lms, blvx
• X-Bonita-App-Key: matching key from BONITA_INTERNAL_APP_KEYS_JSON

License

See LICENSE.