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:

{
  "name": "gpt-4",
  "type": "llm",
  "config": {
    "model": "gpt-4",
    "temperature": 0.7,
    "api_key": "${OPENAI_API_KEY}"
  },
  "is_default": true
}

Response: 201 Created

{
  "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

[
  {
    "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:

{
  "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:

{
  "name": "company-docs",
  "description": "Internal company documentation"
}

Response: 201 Created

{
  "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:

{
  "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

{
  "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:

{
  "query": "What is LangChain?",
  "k": 3,
  "embedding_name": "text-embedding-ada-002"
}

Response: 200 OK

{
  "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

{
  "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:

{
  "user_id": 123,
  "title": "Product Questions"
}

Response: 201 Created

{
  "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

[
  {
    "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:

{
  "user_input": "What is RAG?",
  "kb_id": 1,
  "llm_name": "gpt-4",
  "use_rag": true
}

Response: 200 OK

{
  "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:

{
  "task": "Calculate the square root of 144 and find information about LangChain agents",
  "kb_id": 1,
  "llm_name": "gpt-4"
}

Response: 200 OK

{
  "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

{
  "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

{
  "detail": "Knowledge base 'company-docs' already exists"
}

404 Not Found

{
  "detail": "Conversation not found: 123"
}

500 Internal Server Error

{
  "detail": "Failed to query knowledge base: ..."
}

---

Environment Variable Substitution

Model configs support environment variable substitution using ${VAR_NAME} syntax:

{
  "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