prism chatbot¶

Start an AI chatbot agent that orchestrates Prism's MCP tools using a natural-language interface. The agent connects to an OpenAI-compatible LLM API and exposes all registered Prism MCP tools (SQL, documents, terminal, testing, etc.) as function-calling capabilities — the LLM decides which tools to call and in what order.

How it works¶

User message → LLM API → tool calls? → execute via MCP → results → LLM API → final answer
                     ↑__________________________|

The agent starts an in-memory Prism MCP server (same tools as prism serve, no HTTP transport needed).
It discovers all registered tools and converts their schemas to OpenAI function-calling format.
It sends the user's message to the LLM API with the tool definitions.
If the LLM responds with tool calls, the agent executes them via the MCP client and feeds the results back. Multiple tool calls in a single response are executed concurrently via asyncio.gather().
This loop repeats until the LLM produces a final text response.

Conversation memory¶

In interactive REPL mode, the agent maintains conversation history across turns — the LLM remembers previous questions and results. Use the clear command to reset the conversation context without exiting.

Error handling¶

Retry with backoff: Transient API failures (HTTP 429, 5xx, timeouts) are retried up to 3 times with exponential backoff (1-30s jitter).
Tool errors: Tool execution failures are fed back to the LLM so it can explain the issue and suggest a fix.
Max iterations: The tool-use loop is capped at 25 iterations to prevent infinite loops.
Context trimming: When conversation history approaches the model's context window, oldest messages are trimmed (system prompt preserved).

Security¶

Tool results are treated as data, not instructions — the system prompt explicitly warns the LLM not to follow commands embedded in tool output.
Tool names are validated against the discovered MCP tool list before execution — unknown tools are rejected with an error message.

Prerequisites¶

You need access to an OpenAI-compatible LLM API. This includes:

Provider	API URL
OpenAI	`https://api.openai.com/v1`
Azure OpenAI	`https://<resource>.openai.azure.com/openai/deployments/<deployment>`
vLLM	`http://localhost:8000/v1`
Ollama	`http://localhost:11434/v1`
LM Studio	`http://localhost:1234/v1`
Any OpenAI-compatible endpoint	`<base-url>/v1`

Configuration¶

Quick start¶

# Save credentials persistently
prism config \
  --chatbot-api-url https://api.openai.com/v1 \
  --chatbot-api-key sk-... \
  --chatbot-model gpt-4o \
  --chatbot-skills-path ./skills

# Start the chatbot (settings are read from config.json)
prism chatbot

Configuration sources (precedence: high → low)¶

Command-line flags — --api-url, --api-key, --model, --skills-path
Environment variables — CHATBOT_API_URL, CHATBOT_API_KEY, CHATBOT_MODEL, CHATBOT_SKILLS_PATH
config.json — written by prism config --chatbot-api-url …

Tip

When you pass --api-url, --api-key, --model, or --skills-path on the command line, they are automatically saved to config.json for future runs. Use --no-save to disable this behaviour.

Usage¶

Interactive mode (REPL)¶

prism chatbot

Drops into an interactive prompt where you can type natural-language requests:

Prism 0.2.1-beta2 — Chatbot Agent
  LLM API: https://api.openai.com/v1
  Model:   gpt-4o
  Skills:  ./skills
  Type 'help' for commands, 'clear' to reset context, 'exit' to quit.

you> What tables exist in the USER namespace?
  thinking...
  → calling execute_sql({"query": "SELECT SqlTableName FROM %Dictionary.ClassDefinition WHERE ..."})...
  ← execute_sql returned: 245 chars

agent> The USER namespace contains 12 tables...

you> Now query the first one
  thinking...
  (agent remembers the previous query and its results)

agent> The first table is...

REPL commands¶

Command	Description
`exit` / `quit`	Exit the chatbot session
`help`	Show available commands
`clear`	Clear conversation history (reset context)

One-shot mode¶

Pass a message as an argument to get a single response:

prism chatbot "What is the IRIS version?"

List loaded skills¶

prism chatbot --list-skills

Options¶

Option	Short	Description
`--api-url`		OpenAI-compatible API base URL
`--api-key`		API key for the LLM provider
`--model`		Model name (default: `gpt-4o`)
`--skills-path`		Path to a folder of markdown skill files
`--save` / `--no-save`		Persist provided flags to `config.json` (default: save)
`--list-skills`		List skill files in the configured path and exit

Skills¶

Skills are markdown (.md) files that are loaded and injected into the agent's system prompt. They provide the LLM with domain-specific instructions on how to use the available tools.

Skill file format¶

Any .md file inside the skills directory is loaded. The file name becomes the skill name (e.g. sql/rest-apis.md → sql/rest-apis).

skills/
├── sql/
│   ├── rest-apis.md       # How to create REST API classes
│   └── queries.md        # SQL query patterns
├── testing.md             # How to run unit tests
└── debugging.md           # Debug workflow guide

Example skill file¶

# Creating a REST API class

1. Use `put_and_compile` to create a class that extends `%CSP.REST`.
2. Define `UrlMap` XData block with route definitions.
3. Each route maps an HTTP method + URL pattern to a class method.
4. Test the endpoint with `execute_sql` using a `CALL` statement.

Example:
- Class: `MyApp.RESTHandler.cls`
- Route: `GET /users` → `GetUsers` method

Available tools¶

The chatbot agent has access to all Prism MCP tools registered on the server. The exact set depends on your configuration:

Category	Count	Condition
Always-on	11	SQL, documents, terminal, testing, indexing
Workspace-gated	2	`IRIS_WORKSPACE` is set (`put_document`, `put_and_compile`)
Debug-gated	9	`IRIS_DEBUG_ENABLED=true` (`debug_*` tools)

See the MCP tool reference for the full list.

Config settings¶

Variable	Default	Description
`CHATBOT_API_URL`	(empty)	OpenAI-compatible API base URL
`CHATBOT_API_KEY`	(empty)	API key for the LLM provider
`CHATBOT_MODEL`	`gpt-4o`	Model name to use
`CHATBOT_SKILLS_PATH`	(empty)	Path to a folder of markdown skill files

Examples¶

Using vLLM (local model)¶

prism chatbot \
  --api-url http://localhost:8000/v1 \
  --api-key dummy \
  --model Qwen/Qwen2.5-72B-Instruct

Using Ollama¶

prism chatbot \
  --api-url http://localhost:11434/v1 \
  --api-key dummy \
  --model llama3.1

One-shot query¶

prism chatbot "List all classes in the MyApp package"

With skills¶

mkdir -p skills
echo "# IRIS SQL Guide\nUse execute_sql for all queries." > skills/sql-guide.md
prism chatbot --skills-path ./skills