swagger-operator-bot

An agentic LangChain chatbot that reads your Swagger spec and operates your API in plain English.

---

What it does

Give it a Swagger/OpenAPI spec and it becomes an autonomous operator for that API. You talk to it in natural language; it figures out which endpoint to call, extracts the parameters from your message, executes the HTTP request, and summarizes the result — all without you touching a curl command.

User: "deactivate service 3 and then list all active services"
 └─► Bot parses intent → DELETE /service/deactivate {id: 3} → GET /service → summarizes result

---

How it works

1. Spec parsing — Reads the Swagger YAML and extracts available actions (method + path + parameters)
2. Prompt construction — Builds a structured prompt listing all actions and injects the user's message
3. LLM reasoning — The LLM returns a JSON blob: {"action": "...", "parameters": {...}, "confidence": 90.0}
4. HTTP execution — The bot performs the actual API call and feeds the response back to the LLM
5. Natural language reply — The LLM summarizes the result in plain English

---

Setup

1. Install dependencies

pip install -r requirements.txt

2. Configure your LLM

Copy .env.example to .env and set your API key (or point to a local Ollama endpoint):

OPENAI_API_KEY=sk-...
# or for local Ollama:
# OLLAMA_BASE_URL=http://localhost:11434

3. Start the example API server (in one terminal)

python example_server/app.py

This starts a simple Flask server with a /service CRUD API documented by example_server/swagger.yaml.

4. Run the chatbot (in another terminal)

python main.py

---

Using your own API

Replace example_server/swagger.yaml with your own Swagger/OpenAPI spec. Point main.py at it:

from core.chatbot import SwaggerChatbot

bot = SwaggerChatbot(
    swagger_path="path/to/your/swagger.yaml",
    base_url="https://your-api.example.com",
    llm=your_langchain_llm
)
bot.chat()

---

Example conversations

>>> what are my current active services
Bot: You have 5 active services — Service One (×4, ID: 1) and Service Three (ID: 3).

>>> can you please deactivate my service 3
Bot: Done. Service 3 deactivated successfully (HTTP 200).

>>> now please activate service 4 for me
Bot: Service 4 has been activated successfully (HTTP 200).

>>> what services does your company have?
Bot: There are 4 services: Service One (1), Service Two (2), Service Three (3), Service Four (4).

---

Tech stack

Component	Library
LLM orchestration	LangChain
API spec parsing	PyYAML
HTTP client	requests
Environment config	python-dotenv

---

License

MIT © Amin Tehrani