langchain-learning-kit/docs/api.md

# 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