465 lines
7.4 KiB
Markdown
465 lines
7.4 KiB
Markdown
# API Documentation
|
|
|
|
## Base URL
|
|
|
|
```
|
|
http://localhost:8000/api/v1
|
|
```
|
|
|
|
## Interactive Documentation
|
|
|
|
FastAPI provides automatic interactive documentation:
|
|
|
|
- **Swagger UI**: http://localhost:8000/docs
|
|
- **ReDoc**: http://localhost:8000/redoc
|
|
|
|
---
|
|
|
|
## Model Management
|
|
|
|
### Create Model
|
|
|
|
**POST** `/models/`
|
|
|
|
Register a new LLM or embedding model configuration.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"name": "gpt-4",
|
|
"type": "llm",
|
|
"config": {
|
|
"model": "gpt-4",
|
|
"temperature": 0.7,
|
|
"api_key": "${OPENAI_API_KEY}"
|
|
},
|
|
"is_default": true
|
|
}
|
|
```
|
|
|
|
**Response:** `201 Created`
|
|
```json
|
|
{
|
|
"id": 1,
|
|
"name": "gpt-4",
|
|
"type": "llm",
|
|
"config": {...},
|
|
"is_default": true,
|
|
"status": "active",
|
|
"created_at": "2024-01-01T00:00:00"
|
|
}
|
|
```
|
|
|
|
### List Models
|
|
|
|
**GET** `/models/?type={llm|embedding}`
|
|
|
|
List all models, optionally filtered by type.
|
|
|
|
**Response:** `200 OK`
|
|
```json
|
|
[
|
|
{
|
|
"id": 1,
|
|
"name": "gpt-4",
|
|
"type": "llm",
|
|
...
|
|
}
|
|
]
|
|
```
|
|
|
|
### Get Model
|
|
|
|
**GET** `/models/{model_id}`
|
|
|
|
Get model details by ID.
|
|
|
|
**Response:** `200 OK`
|
|
|
|
### Update Model
|
|
|
|
**PATCH** `/models/{model_id}`
|
|
|
|
Update model configuration.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"config": {"temperature": 0.5},
|
|
"status": "inactive"
|
|
}
|
|
```
|
|
|
|
### Delete Model
|
|
|
|
**DELETE** `/models/{model_id}`
|
|
|
|
Delete a model configuration.
|
|
|
|
**Response:** `204 No Content`
|
|
|
|
---
|
|
|
|
## Knowledge Base Management
|
|
|
|
### Create Knowledge Base
|
|
|
|
**POST** `/kb/`
|
|
|
|
Create a new knowledge base.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"name": "company-docs",
|
|
"description": "Internal company documentation"
|
|
}
|
|
```
|
|
|
|
**Response:** `201 Created`
|
|
```json
|
|
{
|
|
"id": 1,
|
|
"name": "company-docs",
|
|
"description": "Internal company documentation",
|
|
"created_at": "2024-01-01T00:00:00"
|
|
}
|
|
```
|
|
|
|
### List Knowledge Bases
|
|
|
|
**GET** `/kb/`
|
|
|
|
List all knowledge bases.
|
|
|
|
### Get Knowledge Base
|
|
|
|
**GET** `/kb/{kb_id}`
|
|
|
|
Get KB details by ID.
|
|
|
|
### Delete Knowledge Base
|
|
|
|
**DELETE** `/kb/{kb_id}`
|
|
|
|
Delete a knowledge base and its FAISS index.
|
|
|
|
**Response:** `204 No Content`
|
|
|
|
### Ingest Documents
|
|
|
|
**POST** `/kb/{kb_id}/ingest`
|
|
|
|
Ingest documents into knowledge base.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"documents": [
|
|
{
|
|
"content": "LangChain is a framework for developing applications powered by language models.",
|
|
"title": "LangChain Introduction",
|
|
"source": "docs/intro.md",
|
|
"metadata": {"category": "tutorial"}
|
|
}
|
|
],
|
|
"embedding_name": "text-embedding-ada-002",
|
|
"background": true
|
|
}
|
|
```
|
|
|
|
**Response:** `200 OK`
|
|
```json
|
|
{
|
|
"job_id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"status": "submitted",
|
|
"message": "Ingestion job submitted with ID: ..."
|
|
}
|
|
```
|
|
|
|
### Query Knowledge Base
|
|
|
|
**POST** `/kb/{kb_id}/query`
|
|
|
|
Search knowledge base using vector similarity.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"query": "What is LangChain?",
|
|
"k": 3,
|
|
"embedding_name": "text-embedding-ada-002"
|
|
}
|
|
```
|
|
|
|
**Response:** `200 OK`
|
|
```json
|
|
{
|
|
"results": [
|
|
{
|
|
"content": "LangChain is a framework...",
|
|
"metadata": {"title": "LangChain Introduction", ...},
|
|
"score": 0.85
|
|
}
|
|
],
|
|
"result_count": 3
|
|
}
|
|
```
|
|
|
|
### Get KB Status
|
|
|
|
**GET** `/kb/{kb_id}/status`
|
|
|
|
Get knowledge base statistics.
|
|
|
|
**Response:** `200 OK`
|
|
```json
|
|
{
|
|
"kb_id": 1,
|
|
"name": "company-docs",
|
|
"description": "...",
|
|
"document_count": 42,
|
|
"index_exists": true,
|
|
"created_at": "2024-01-01T00:00:00"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Conversations
|
|
|
|
### Create Conversation
|
|
|
|
**POST** `/conversations/`
|
|
|
|
Create a new conversation.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"user_id": 123,
|
|
"title": "Product Questions"
|
|
}
|
|
```
|
|
|
|
**Response:** `201 Created`
|
|
```json
|
|
{
|
|
"id": 1,
|
|
"user_id": 123,
|
|
"title": "Product Questions",
|
|
"created_at": "2024-01-01T00:00:00"
|
|
}
|
|
```
|
|
|
|
### Get Conversation
|
|
|
|
**GET** `/conversations/{conversation_id}`
|
|
|
|
Get conversation details.
|
|
|
|
### Delete Conversation
|
|
|
|
**DELETE** `/conversations/{conversation_id}`
|
|
|
|
Delete a conversation and all its messages.
|
|
|
|
**Response:** `204 No Content`
|
|
|
|
### Get Messages
|
|
|
|
**GET** `/conversations/{conversation_id}/messages?limit=50&offset=0`
|
|
|
|
Get messages from conversation with pagination.
|
|
|
|
**Response:** `200 OK`
|
|
```json
|
|
[
|
|
{
|
|
"id": 1,
|
|
"conversation_id": 1,
|
|
"role": "user",
|
|
"content": "What is RAG?",
|
|
"msg_metadata": {},
|
|
"created_at": "2024-01-01T00:00:00"
|
|
},
|
|
{
|
|
"id": 2,
|
|
"conversation_id": 1,
|
|
"role": "assistant",
|
|
"content": "RAG stands for Retrieval-Augmented Generation...",
|
|
"msg_metadata": {
|
|
"sources": [...],
|
|
"model": "gpt-4"
|
|
},
|
|
"created_at": "2024-01-01T00:00:05"
|
|
}
|
|
]
|
|
```
|
|
|
|
### Chat
|
|
|
|
**POST** `/conversations/{conversation_id}/chat`
|
|
|
|
Send a message and get assistant response.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"user_input": "What is RAG?",
|
|
"kb_id": 1,
|
|
"llm_name": "gpt-4",
|
|
"use_rag": true
|
|
}
|
|
```
|
|
|
|
**Response:** `200 OK`
|
|
```json
|
|
{
|
|
"message_id": 2,
|
|
"conversation_id": 1,
|
|
"role": "assistant",
|
|
"content": "RAG stands for Retrieval-Augmented Generation...",
|
|
"metadata": {
|
|
"sources": [
|
|
{"title": "RAG Overview", "source": "docs/rag.md"}
|
|
],
|
|
"model": "gpt-4"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Agent Execution
|
|
|
|
### Execute Agent
|
|
|
|
**POST** `/agent/execute`
|
|
|
|
Execute an agent task with available tools.
|
|
|
|
**Available Tools:**
|
|
- `calculator`: Mathematical calculations
|
|
- `knowledge_base_search`: Vector search (if kb_id provided)
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"task": "Calculate the square root of 144 and find information about LangChain agents",
|
|
"kb_id": 1,
|
|
"llm_name": "gpt-4"
|
|
}
|
|
```
|
|
|
|
**Response:** `200 OK`
|
|
```json
|
|
{
|
|
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"output": "The square root of 144 is 12. Based on the knowledge base, LangChain agents are...",
|
|
"success": true
|
|
}
|
|
```
|
|
|
|
### Get Agent Logs
|
|
|
|
**GET** `/agent/logs/{agent_id}?limit=50&offset=0`
|
|
|
|
Get tool call logs for an agent execution.
|
|
|
|
**Response:** `200 OK`
|
|
```json
|
|
{
|
|
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"tool_calls": [
|
|
{
|
|
"id": 1,
|
|
"agent_id": "550e8400-...",
|
|
"tool_name": "calculator",
|
|
"call_input": {"tool_input": "sqrt(144)"},
|
|
"call_output": {"observation": "sqrt(144) = 12.0"},
|
|
"created_at": "2024-01-01T00:00:01"
|
|
},
|
|
{
|
|
"id": 2,
|
|
"agent_id": "550e8400-...",
|
|
"tool_name": "knowledge_base_search",
|
|
"call_input": {
|
|
"tool_input": {"query": "LangChain agents", "kb_id": 1, "k": 3}
|
|
},
|
|
"call_output": {
|
|
"observation": "[1] (Relevance: 0.89) LangChain agents are..."
|
|
},
|
|
"created_at": "2024-01-01T00:00:02"
|
|
}
|
|
],
|
|
"total_calls": 2
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Error Responses
|
|
|
|
### 400 Bad Request
|
|
```json
|
|
{
|
|
"detail": "Knowledge base 'company-docs' already exists"
|
|
}
|
|
```
|
|
|
|
### 404 Not Found
|
|
```json
|
|
{
|
|
"detail": "Conversation not found: 123"
|
|
}
|
|
```
|
|
|
|
### 500 Internal Server Error
|
|
```json
|
|
{
|
|
"detail": "Failed to query knowledge base: ..."
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Environment Variable Substitution
|
|
|
|
Model configs support environment variable substitution using `${VAR_NAME}` syntax:
|
|
|
|
```json
|
|
{
|
|
"name": "gpt-4",
|
|
"config": {
|
|
"model": "gpt-4",
|
|
"api_key": "${OPENAI_API_KEY}",
|
|
"base_url": "${OPENAI_BASE_URL}"
|
|
}
|
|
}
|
|
```
|
|
|
|
Variables are replaced at runtime with values from environment or `.env` file.
|
|
|
|
---
|
|
|
|
## Rate Limiting
|
|
|
|
Currently not implemented. For production use, consider adding:
|
|
- Per-user rate limits
|
|
- Per-endpoint throttling
|
|
- Token bucket algorithm
|
|
- Redis-based rate limiting
|
|
|
|
---
|
|
|
|
## Authentication
|
|
|
|
Currently not implemented. The API is open for development/learning purposes.
|
|
|
|
For production use, implement:
|
|
- JWT-based authentication
|
|
- API key authentication
|
|
- Role-based access control (RBAC)
|
|
- OAuth2/OpenID Connect
|