TopicLab-Agent

AI-powered expert assistant for TopicLab-CLI

An intelligent assistant designed for topiclab-cli --ask that provides instant, command-first answers.

Quick Start • Documentation • API Reference • Examples

---

🎯 What is TopicLab-Agent?

TopicLab-Agent is an intelligent assistant designed to answer questions from topiclab-cli --ask. It provides direct, actionable topiclab commands based on TopicLab Skill documentation and source code analysis.

Perfect companion for TopicLab-CLI 🤝

✨ Key Features

• 🎯 Single-turn Responses - Complete answers in one shot, no back-and-forth
• ⚡ Command-first - Direct topiclab-cli commands, no fluff
• 📚 Knowledge-powered - Based on Skill docs + TopicLab-CLI source code
• 🔄 Auto-updating - Refreshes Skill documentation every 3 hours
• 🚀 API-ready - RESTful & OpenAI-compatible endpoints
• 🤖 Agent-based - Built with LangChain & LangGraph
• 💾 Database Logging - Automatic request/response logging (SQLite by default)

🚀 Quick Start

Prerequisites

• Python 3.12+
• API keys (automatically configured in environment)

Note: Database logging uses SQLite by default (stored in data/topiclab.db). No additional setup required!

Installation

# Clone the repository
git clone https://github.com/TashanGKD/TopicLab-Agent.git
cd TopicLab-Agent

# Install dependencies
pip install -r requirements.txt

Start the Service

# Method 1: Direct start
python src/main.py

# Method 2: Using script
./scripts/start_service.sh

Service will be available at: http://localhost:8000

Note: Request logs are automatically stored in data/topiclab.db (SQLite). No database setup required!

Make Your First Request

# Using curl
curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"type": "human", "content": "How to initialize topiclab-cli?"}
    ]
  }'

# Using Python client
python scripts/api_client.py "How to initialize topiclab-cli?"

📖 Documentation

• API Usage Guide - Complete API documentation
• Database Logging - Request logging and analytics
• TopicLab-CLI - Official CLI tool

🛠️ API Endpoints

Endpoint	Method	Description
/run	POST	Synchronous call (recommended)
/stream	POST	Streaming call (SSE)
/v1/chat/completions	POST	OpenAI-compatible interface
/logs	GET	Retrieve request logs from database
/docs	GET	Interactive API documentation

💡 Usage Examples

Python Example

from scripts.api_client import ask_question

# Ask a question
result = ask_question("How to initialize topiclab-cli?")
print(result["answer"])
# Output: topiclab session ensure --base-url https://world.tashan.chat --bind-key <YOUR_KEY> --json

JavaScript/TypeScript Example

const response = await fetch('http://localhost:8000/run', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    messages: [{type: 'human', content: 'Show notifications'}]
  })
});

const result = await response.json();
console.log(result.messages[result.messages.length - 1].content);
// Output: topiclab notifications list --json

cURL Example

# Synchronous call
curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"type": "human", "content": "Check twin info"}
    ]
  }'

# OpenAI-compatible interface
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "topiclab-agent",
    "messages": [
      {"role": "user", "content": "Start a discussion"}
    ],
    "stream": false
  }'

🏗️ Project Structure

TopicLab-Agent/
├── config/                 # Configuration files
│   └── agent_llm_config.json
├── docs/                   # Documentation
│   └── API_USAGE.md
├── scripts/                # Utility scripts
│   ├── api_client.py       # Python client
│   ├── test_api.py         # Test script
│   └── start_service.sh    # Startup script
├── src/
│   ├── agents/            # Agent implementation
│   │   └── agent.py
│   ├── tools/             # Custom tools
│   │   └── topiclab_skill_tool.py
│   └── main.py            # FastAPI server
├── assets/                # Data and resources
├── tests/                 # Unit tests
├── requirements.txt       # Python dependencies
└── README.md             # This file

🔧 How It Works

1. Document Auto-Update: Automatically fetches the latest TopicLab Skill documentation every 3 hours
2. Source Code Analysis: Understands topiclab-cli commands from GitHub source code
3. Intelligent Retrieval: Uses keyword matching to find relevant information
4. Command-First Output: Generates direct, executable topiclab commands

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone the repo
git clone https://github.com/TashanGKD/TopicLab-Agent.git
cd TopicLab-Agent

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run tests
python scripts/test_api.py

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• TopicLab-CLI - The official CLI tool this agent assists with
• LangChain - Framework for building the agent
• FastAPI - Modern web framework for building APIs

---

Made with ❤️ by TashanGKD