Documentação
Backend SDK - API Reference

Clara Context API

Documentação completa da API REST do Clara Context Backend

Introdução

O Clara Context Backend é uma API REST completa construída com FastAPI que fornece gerenciamento de contexto com memória infinita para aplicações LLM. A API integra-se com Graphiti (Neo4j), PostgreSQL com pgvector, Redis, e suporta múltiplos provedores de LLM.

Características Principais

  • Autenticação JWT com OAuth2
  • Gerenciamento de projetos e assistentes
  • RAG (Retrieval Augmented Generation)
  • Integração com Graphiti para memória de longo prazo
  • Vector storage com pgvector
  • Rate limiting e caching com Redis
  • Documentação automática (Swagger/ReDoc)

Base URL:

http://localhost:8000/app

Instalação

Pré-requisitos

  • Python 3.11+
  • PostgreSQL 15+ com extensão pgvector
  • Neo4j para Graphiti
  • Redis para cache e rate limiting

Configuração

# 1. Clone o repositório
git clone https://github.com/your-repo/clara-context
cd clara-context

# 2. Instale dependências
pip install -r app/requirements.txt

# 3. Configure variáveis de ambiente (.env)
OPENAI_API_KEY=your-key
NEO4J_USER=neo4j
NEO4J_PASSWORD=your-password
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
REDIS_URL=redis://redis:6379/0
JWT_SECRET_KEY=your-secret-key

# 4. Execute migrations
cd app/backend
alembic upgrade head

# 5. Inicie a API
cd ..
uvicorn backend.app:app --reload --host 0.0.0.0 --port 8000

API estará disponível em: http://localhost:8000/app/docs

Autenticação

A API usa JWT (JSON Web Tokens) para autenticação. Suporta registro com email/senha e OAuth (Google, GitHub).

Endpoints de Autenticação

POST/api/auth/register

Registrar novo usuário com email e senha.

Request Body:

{
  "email": "user@example.com",
  "username": "johndoe",
  "password": "strongPassword123",
  "full_name": "John Doe",
  "bio": "Developer",
  "avatar_url": "https://..."
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1...",
  "token_type": "bearer",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "username": "johndoe",
    ...
  }
}
POST/api/auth/login/json

Login com email e senha.

Request Body:

{
  "email": "user@example.com",
  "password": "strongPassword123"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1...",
  "token_type": "bearer",
  "user": { ... }
}
POST/api/auth/oauth/direct-sync

Sincronizar usuário OAuth (Google, GitHub).

{
  "email": "user@gmail.com",
  "full_name": "John Doe",
  "provider": "google",
  "provider_id": "google-user-id",
  "avatar_url": "https://..."
}
GET/api/auth/me

Obter dados do usuário autenticado.

Requer autenticação: Bearer Token no header

Como usar o token

// Em todos os requests autenticados, adicione o header:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Usuários

GET/api/users

Listar todos os usuários (paginado).

Query params: skip=0&limit=100

GET/api/users/{user_id}

Obter usuário por ID.

PATCH/api/users/{user_id}

Atualizar dados do usuário.

{
  "username": "newusername",
  "full_name": "New Name",
  "bio": "Updated bio",
  "avatar_url": "https://...",
  "preferences": {
    "theme": "dark",
    "language": "pt-BR"
  }
}
DELETE/api/users/{user_id}

Deletar usuário.

Projetos

Projetos são workspaces que agrupam assistentes, conversações e membros.

POST/api/projects

Criar novo projeto.

{
  "name": "My AI Project",
  "description": "Customer support assistant",
  "is_public": false,
  "color": "#3B82F6",
  "icon": "robot",
  "tags": ["customer-support", "chatbot"],
  "settings": {
    "max_assistants": 10,
    "allow_public_chat": false
  }
}
GET/api/projects

Listar projetos do usuário.

Query params: skip=0&limit=100&is_public=false

GET/api/projects/{project_id}

Obter projeto com detalhes do owner.

GET/api/projects/{project_id}/members

Listar membros do projeto com roles.

POST/api/projects/{project_id}/members

Adicionar membro ao projeto.

{
  "user_id": "uuid",
  "role": "member"  // owner, admin, member, viewer
}

Assistentes

Assistentes são agentes de IA configuráveis com modelos LLM, RAG e memória Graphiti.

POST/api/assistants

Criar novo assistente.

{
  "name": "Customer Support Bot",
  "description": "Helpful AI assistant",
  "project_id": "uuid",
  "primary_model_provider": "openai",
  "primary_model_type": "gpt-4o",
  "model_parameters": {
    "temperature": 0.7,
    "max_tokens": 2000
  },
  "system_instructions": "You are a helpful assistant...",
  "rag_enabled": true,
  "vector_storage_backend": "pgvector",
  "embedding_model": "text-embedding-3-small",
  "graph_backend": "neo4j",
  "enabled_tools": ["search", "calculator"]
}
GET/api/assistants?project_id={uuid}

Listar assistentes de um projeto.

POST/api/assistants/{assistant_id}/chat

Conversar com o assistente.

Request:

{
  "message": "Como posso resetar minha senha?",
  "conversation_id": "uuid",  // opcional
  "context": {
    "user_email": "user@example.com"
  }
}

Response:

{
  "response": "Para resetar sua senha...",
  "assistant_id": "uuid",
  "conversation_id": "uuid"
}
POST/api/assistants/{assistant_id}/documents

Adicionar documento ao assistente (RAG).

{
  "content": "FAQ content here...",
  "source_type": "document",
  "source_id": "doc-123",
  "metadata": {
    "title": "FAQ",
    "category": "support"
  },
  "chunk_size": 500,
  "chunk_overlap": 50
}
POST/api/assistants/{assistant_id}/search

Buscar documentos vetoriais.

{
  "query": "password reset",
  "top_k": 5,
  "similarity_threshold": 0.7
}

Conversações

POST/api/conversations

Criar nova conversação.

{
  "assistant_id": "uuid",
  "title": "Support Chat #123",
  "metadata": {
    "channel": "web",
    "user_ip": "192.168.1.1"
  }
}
GET/api/conversations/{conversation_id}/messages

Obter histórico de mensagens.

POST/api/conversations/{conversation_id}/messages

Adicionar mensagem à conversação.

{
  "content": "Hello, how are you?",
  "role": "user",  // user, assistant, system
  "metadata": {}
}

Chat & Graphiti

Endpoint principal de chat com busca semântica híbrida e memória Graphiti.

POST/chat

Chat com Clara AI usando Graphiti para contexto.

Request:

{
  "content": "What did we discuss last time?"
}

Response:

{
  "response": "Last time we discussed...",
  "used_context": [
    {
      "uuid": "edge-uuid",
      "fact": "User discussed X",
      "valid_at": "2024-01-15",
      "source_node_uuid": "node-uuid"
    }
  ]
}

Como Funciona

  1. Busca híbrida no grafo Graphiti (Neo4j)
  2. Cross-encoder para re-ranking
  3. Contexto relevante injetado no prompt
  4. Resposta gerada com Clara AI
  5. Nova informação adicionada ao grafo

Documentos

POST/api/documents

Upload de documento (qualquer tipo).

// Multipart form-data
file: <binary file>
GET/api/documents

Listar todos os documentos.

GET/api/documents/{document_id}/download

Download do documento original.

DELETE/api/documents/{document_id}

Deletar documento.

Grupos

Grupos organizam usuários e projetos para melhor controle de acesso.

POST/api/groups

Criar novo grupo.

{
  "name": "Engineering Team",
  "description": "Core engineering",
  "is_active": true,
  "settings": {}
}
POST/api/groups/{group_id}/members

Adicionar membro ao grupo.

{
  "user_id": "uuid",
  "role": "member"
}

Dashboard

GET/api/dashboard/stats

Estatísticas gerais do sistema.

Response:

{
  "total_users": 150,
  "total_projects": 42,
  "total_assistants": 89,
  "total_conversations": 1234,
  "active_users_today": 45,
  "messages_today": 567
}

Tratamento de Erros

400 Bad Request

Dados de entrada inválidos.

{
  "detail": "Email already registered"
}

401 Unauthorized

Token inválido ou ausente.

{
  "detail": "Could not validate credentials"
}

403 Forbidden

Sem permissão para acessar recurso.

{
  "detail": "You don't have access to this project"
}

404 Not Found

Recurso não encontrado.

{
  "detail": "Assistant not found"
}

429 Too Many Requests

Rate limit excedido.

{
  "detail": "Rate limit exceeded: 10 per minute"
}

500 Internal Server Error

Erro no servidor.

{
  "detail": "An error occurred: ..."
}

Rate Limiting

Limites por Endpoint

/api/auth/register10 req/hora
/api/auth/login/*10 req/minuto
/chatPadrão do app
Outros endpointsSem limite

Headers de Rate Limit

Quando o rate limit é atingido, a API retorna:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200
Retry-After: 60