API_DATA_STRUCTURES.md

Cidadão.AI Backend API Data Structures

This document provides a comprehensive reference for all Pydantic models, request/response schemas, and data structures used in the Cidadão.AI backend API that a frontend application would need to implement.

Table of Contents

1. Chat API Models
2. WebSocket Models
3. Investigation Models
4. Authentication Models
5. Agent Models
6. Pagination Models
7. Error Response Format

---

Chat API Models

ChatRequest

class ChatRequest(BaseModel):
    """Chat message request"""
    message: str  # min_length=1, max_length=1000
    session_id: Optional[str] = None
    context: Optional[Dict[str, Any]] = None

ChatResponse

class ChatResponse(BaseModel):
    """Chat message response"""
    session_id: str
    agent_id: str
    agent_name: str
    message: str
    confidence: float
    suggested_actions: Optional[List[str]] = None
    requires_input: Optional[Dict[str, str]] = None
    metadata: Dict[str, Any] = {}

QuickAction

class QuickAction(BaseModel):
    """Quick action suggestion"""
    id: str
    label: str
    icon: str
    action: str

Stream Response Format (SSE)

// Server-Sent Events format for /api/v1/chat/stream
data: {"type": "start", "timestamp": "2025-01-19T12:00:00Z"}
data: {"type": "detecting", "message": "Analisando sua mensagem..."}
data: {"type": "intent", "intent": "investigate", "confidence": 0.92}
data: {"type": "agent_selected", "agent_id": "zumbi", "agent_name": "Zumbi dos Palmares"}
data: {"type": "chunk", "content": "Olá! Sou Zumbi dos Palmares..."}
data: {"type": "complete", "suggested_actions": ["start_investigation", "learn_more"]}
data: {"type": "error", "message": "Erro ao processar mensagem"}

---

WebSocket Models

WebSocketMessage

class WebSocketMessage(BaseModel):
    """WebSocket message structure"""
    type: str  # Message type
    data: Dict[str, Any] = {}
    timestamp: datetime = Field(default_factory=datetime.utcnow)
    id: str = Field(default_factory=lambda: str(uuid4()))

WebSocket Connection URL

ws://localhost:8000/api/v1/ws/chat/{session_id}?token={jwt_token}

WebSocket Message Types

Client to Server

// Send chat message
{
    "type": "chat_message",
    "data": {
        "message": "Investigar contratos do Ministério da Saúde",
        "context": {}
    }
}

// Subscribe to investigation
{
    "type": "subscribe_investigation",
    "data": {
        "investigation_id": "123e4567-e89b-12d3-a456-426614174000"
    }
}

// Unsubscribe from investigation
{
    "type": "unsubscribe_investigation",
    "data": {
        "investigation_id": "123e4567-e89b-12d3-a456-426614174000"
    }
}

// Keep alive ping
{
    "type": "ping",
    "data": {}
}

Server to Client

// Connection established
{
    "type": "connection",
    "data": {
        "status": "connected",
        "session_id": "abc123",
        "message": "Conectado ao Cidadão.AI em tempo real"
    },
    "timestamp": "2025-01-19T12:00:00Z",
    "id": "msg123"
}

// Agent response
{
    "type": "agent_response",
    "data": {
        "agent_id": "zumbi",
        "agent_name": "Zumbi dos Palmares",
        "message": "Encontrei 15 anomalias nos contratos...",
        "confidence": 0.92,
        "metadata": {
            "processing_time_ms": 1250,
            "anomalies_found": 15
        }
    }
}

// Investigation update
{
    "type": "investigation_update",
    "data": {
        "investigation_id": "123e4567",
        "status": "processing",
        "progress": 0.75,
        "current_phase": "analyzing_patterns",
        "anomalies_detected": 12
    }
}

// Error message
{
    "type": "error",
    "data": {
        "code": "PROCESSING_ERROR",
        "message": "Failed to process request",
        "details": {}
    }
}

// Pong response
{
    "type": "pong",
    "data": {}
}

---

Investigation Models

InvestigationRequest

class InvestigationRequest(BaseModel):
    """Request model for starting an investigation"""
    query: str  # Investigation query or focus area
    data_source: str = "contracts"  # One of: contracts, expenses, agreements, biddings, servants
    filters: Dict[str, Any] = {}
    anomaly_types: List[str] = ["price", "vendor", "temporal", "payment"]
    include_explanations: bool = True
    stream_results: bool = False

InvestigationResponse

class InvestigationResponse(BaseModel):
    """Response model for investigation results"""
    investigation_id: str
    status: str
    query: str
    data_source: str
    started_at: datetime
    completed_at: Optional[datetime] = None
    anomalies_found: int
    total_records_analyzed: int
    results: List[Dict[str, Any]]
    summary: str
    confidence_score: float
    processing_time: float

AnomalyResult

class AnomalyResult(BaseModel):
    """Individual anomaly result"""
    anomaly_id: str
    type: str  # price, vendor, temporal, payment, duplicate, pattern
    severity: str  # low, medium, high, critical
    confidence: float
    description: str
    explanation: str
    affected_records: List[Dict[str, Any]]
    suggested_actions: List[str]
    metadata: Dict[str, Any]

InvestigationStatus

class InvestigationStatus(BaseModel):
    """Investigation status response"""
    investigation_id: str
    status: str  # started, processing, completed, failed
    progress: float  # 0.0 to 1.0
    current_phase: str
    records_processed: int
    anomalies_detected: int
    estimated_completion: Optional[datetime] = None

---

Authentication Models

LoginRequest

class LoginRequest(BaseModel):
    email: str  # EmailStr
    password: str

LoginResponse

class LoginResponse(BaseModel):
    access_token: str
    refresh_token: str
    token_type: str = "bearer"
    expires_in: int  # seconds
    user: {
        "id": str,
        "email": str,
        "name": str,
        "role": str,
        "is_active": bool
    }

RefreshRequest

class RefreshRequest(BaseModel):
    refresh_token: str

RefreshResponse

class RefreshResponse(BaseModel):
    access_token: str
    token_type: str = "bearer"
    expires_in: int  # seconds

RegisterRequest

class RegisterRequest(BaseModel):
    email: str  # EmailStr
    password: str
    name: str
    role: Optional[str] = "analyst"

UserResponse

class UserResponse(BaseModel):
    id: str
    email: str
    name: str
    role: str
    is_active: bool
    created_at: datetime
    last_login: Optional[datetime] = None

Authorization Header

Authorization: Bearer {access_token}

---

Agent Models

AgentMessage

class AgentMessage(BaseModel):
    """Message passed between agents"""
    sender: str  # Agent that sent the message
    recipient: str  # Agent that should receive the message
    action: str  # Action to perform
    payload: Dict[str, Any] = {}
    context: Dict[str, Any] = {}
    timestamp: datetime
    message_id: str
    requires_response: bool = True

AgentResponse

class AgentResponse(BaseModel):
    """Response from an agent"""
    agent_name: str
    status: str  # IDLE, PROCESSING, COMPLETED, ERROR, REFLECTING
    result: Optional[Any] = None
    error: Optional[str] = None
    metadata: Dict[str, Any] = {}
    timestamp: datetime
    processing_time_ms: Optional[float] = None

Available Agents

const AGENTS = {
    abaporu: { name: "Abaporu", role: "Orquestrador" },
    zumbi: { name: "Zumbi dos Palmares", role: "Investigador" },
    anita: { name: "Anita Garibaldi", role: "Analista" },
    tiradentes: { name: "Tiradentes", role: "Relator" },
    machado: { name: "Machado de Assis", role: "Textual" },
    dandara: { name: "Dandara", role: "Justiça Social" },
    drummond: { name: "Carlos Drummond de Andrade", role: "Comunicação" }
}

---

Pagination Models

CursorPaginationRequest

class CursorPaginationRequest(BaseModel):
    """Request parameters for cursor pagination"""
    cursor: Optional[str] = None  # Base64 encoded cursor
    limit: int = 20  # min=1, max=100
    direction: str = "next"  # next or prev

CursorPaginationResponse

class CursorPaginationResponse(BaseModel):
    """Response with cursor pagination metadata"""
    items: List[T]
    next_cursor: Optional[str] = None
    prev_cursor: Optional[str] = None
    has_more: bool = False
    total_items: Optional[int] = None
    metadata: Dict[str, Any] = {}

Cursor Format

// Cursor is base64 encoded JSON
{
    "t": "2025-01-19T12:00:00Z",  // timestamp
    "i": "123e4567",               // id
    "d": "next"                    // direction
}

---

Error Response Format

All API errors follow this standardized format:

HTTP Exception Response

{
    "status": "error",
    "status_code": 400,  // HTTP status code
    "error": {
        "error": "HTTPException",
        "message": "Invalid request data",
        "details": {}
    }
}

Application Error Response

{
    "status": "error",
    "status_code": 500,
    "error": {
        "error": "InternalServerError",
        "message": "An unexpected error occurred",
        "details": {
            "error_type": "DatabaseConnectionError"  // Only in development
        }
    }
}

Custom Exception Format (CidadaoAIError)

{
    "error": "AgentExecutionError",  // Error code
    "message": "Agent failed to execute task",
    "details": {
        "agent": "zumbi",
        "action": "investigate",
        "error": "Connection timeout"
    }
}

---

Common HTTP Status Codes

• 200 OK - Success
• 201 Created - Resource created
• 400 Bad Request - Invalid request data
• 401 Unauthorized - Missing or invalid authentication
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 422 Unprocessable Entity - Validation error
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error

---

API Base URLs

Development

http://localhost:8000/api/v1
ws://localhost:8000/api/v1/ws

Production (HuggingFace Spaces)

https://neural-thinker-cidadao-ai-backend.hf.space/api/v1
wss://neural-thinker-cidadao-ai-backend.hf.space/api/v1/ws

---

TypeScript Interface Examples

For TypeScript frontend implementations, here are the equivalent interfaces:

// Chat interfaces
interface ChatRequest {
    message: string;
    session_id?: string;
    context?: Record<string, any>;
}

interface ChatResponse {
    session_id: string;
    agent_id: string;
    agent_name: string;
    message: string;
    confidence: number;
    suggested_actions?: string[];
    requires_input?: Record<string, string>;
    metadata: Record<string, any>;
}

// WebSocket interfaces
interface WebSocketMessage {
    type: string;
    data: Record<string, any>;
    timestamp: string;
    id: string;
}

// Investigation interfaces
interface InvestigationRequest {
    query: string;
    data_source?: 'contracts' | 'expenses' | 'agreements' | 'biddings' | 'servants';
    filters?: Record<string, any>;
    anomaly_types?: string[];
    include_explanations?: boolean;
    stream_results?: boolean;
}

// Error interface
interface ErrorResponse {
    status: 'error';
    status_code: number;
    error: {
        error: string;
        message: string;
        details: Record<string, any>;
    };
}

---

Notes for Frontend Developers

1. Authentication: All authenticated endpoints require the Authorization: Bearer {token} header
2. WebSocket: Connect with JWT token as query parameter for authentication
3. Pagination: Use cursor-based pagination for chat history and large datasets
4. Error Handling: Always check for error responses and handle appropriately
5. SSE Streaming: For real-time responses, use EventSource API with /api/v1/chat/stream
6. Rate Limiting: Respect rate limits indicated in response headers
7. Timestamp Format: All timestamps are in ISO 8601 format (UTC)
8. IDs: All entity IDs are UUIDs in string format