Version: 1.0.0 Last Updated: 2026-05-14 Status: Active

bast-cat-api¶

Version: 0.2.11 Module: bast_cat_api Path: src/apis/cat

Overview¶

Chat processing, conversation management, and configuration synchronization API with modular architecture supporting both legacy and Agno-based chat processing.

Features¶

Chat Processing¶

Dynamic chat mode routing (legacy/agno/custom)
Unified chat endpoint with configuration-based routing
Streaming response support
Context management

Conversation Management¶

List conversations
Get conversation history
Delete conversations
Rename conversations
Search conversations

Configuration¶

Runtime configuration synchronization
Chat mode switching
Model parameter updates

Endpoints¶

Chat Endpoints¶

Endpoint	Method	Description
`/api/v1/cat/chat`	POST	Unified chat with dynamic routing
`/api/v1/cat/agno_chat`	POST	Direct Agno chat endpoint
`/api/v1/cat/legacy_chat`	POST	Direct legacy chat endpoint

Conversation Endpoints¶

Endpoint	Method	Description
`/api/v1/cat/conversations`	GET	List user's conversations
`/api/v1/cat/conversations/{id}`	GET	Get conversation history
`/api/v1/cat/conversations/{id}`	DELETE	Delete conversation
`/api/v1/cat/conversations/{id}/rename`	PUT	Rename conversation
`/api/v1/cat/conversations/search`	GET	Search conversations

Configuration Endpoints¶

Endpoint	Method	Description
`/api/v1/cat/config`	GET	Get current configuration
`/api/v1/cat/config/sync`	POST	Sync configuration

Chat Request/Response¶

Request Schema¶

class ChatRequest(BaseModel):
    message: str
    conversation_id: str | None = None
    context: dict | None = None
    stream: bool = False
    model: str | None = None  # Override default model

Response Schema¶

class ChatResponse(BaseModel):
    message: str
    conversation_id: str
    model: str
    tokens_used: int | None = None
    sources: list[dict] | None = None

Chat Mode Routing¶

The unified /chat endpoint routes requests based on configuration:

Mode	Handler	Description
`legacy`	`legacy_chat.py`	Multi-model processing pipeline
`agno`	`agno_chat.py`	Agno agent processing
`custom`	Configurable	Custom routing logic

Configuration¶

# resources/config/{catname}.yaml
cat:
  chat_mode: agno  # "legacy", "agno", or "custom"

  agno:
    model: gpt-4o
    instructions: "You are a helpful assistant."

  legacy:
    models:
      - greeting
      - intent
      - qa
      - default

Modular Architecture¶

src/apis/cat/
├── bast_cat_api/
│   ├── __init__.py
│   ├── main.py              # FastAPI app
│   ├── routers/
│   │   ├── cat.py           # Main router with routing
│   │   ├── legacy_chat.py   # Legacy chat handler
│   │   ├── agno_chat.py     # Agno chat handler
│   │   ├── conversations.py # Conversation management
│   │   └── config.py        # Configuration sync
│   └── models/
│       ├── requests.py      # Request models
│       └── responses.py     # Response models

Dependencies¶

Internal Dependencies¶

Package	Purpose
bast-api-base	Core API setup
bast-ai-dvc	Data version control
bast-model-base	Model management
bast-model-early-exit	Early exit detection
bast-model-nothing-found	No results handling

Usage Examples¶

Basic Chat Request¶

curl -X POST http://localhost:8000/api/v1/cat/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "message": "What is machine learning?",
    "conversation_id": null
  }'

Streaming Chat¶

curl -X POST http://localhost:8000/api/v1/cat/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "message": "Tell me a story",
    "stream": true
  }'

List Conversations¶

curl http://localhost:8000/api/v1/cat/conversations \
  -H "Authorization: Bearer $TOKEN"

Get Conversation History¶

curl http://localhost:8000/api/v1/cat/conversations/abc123 \
  -H "Authorization: Bearer $TOKEN"

Delete Conversation¶

curl -X DELETE http://localhost:8000/api/v1/cat/conversations/abc123 \
  -H "Authorization: Bearer $TOKEN"

Testing¶

Running Tests¶

pants test src/apis/cat:: -- -s --no-header

Manual Testing¶

import requests

# Chat request
response = requests.post(
    "http://localhost:8000/api/v1/cat/chat",
    json={"message": "Hello", "conversation_id": None},
    headers={"Authorization": "Bearer token"}
)
print(response.json())

Issues & Improvements¶

Current Issues¶

No rate limiting: Unlimited requests per user
Basic conversation search: Full-text only
Limited streaming: Not all models support streaming

Suggested Improvements¶

Rate limiting: Add per-user rate limits
Enhanced search: Add semantic search for conversations
Conversation export: Export conversation history
Message reactions: Support user feedback on messages
Typing indicators: WebSocket support for typing
Message editing: Allow editing previous messages

Changelog¶

v0.2.11 (Current)¶

Improved Agno chat handler
Better streaming support

v0.2.10¶

Added conversation search
Fixed memory leaks

v0.2.9¶

Modular router architecture
Configuration sync endpoint