Advanced ChatRoom Usage

Programmatic usage and advanced configuration for ChatRoom.

Programmatic Usage

Basic Usage

import asyncio
from pantheon.chatroom import ChatRoom

async def main():
    chatroom = ChatRoom()

    # Start and get service info
    info = await chatroom.start()
    print(f"Service ID: {info.service_id}")

    # Keep running
    await asyncio.Event().wait()

asyncio.run(main())

With Custom Endpoint

from pantheon.chatroom import ChatRoom
from pantheon.endpoint import Endpoint

endpoint = Endpoint(workspace_path="./my_workspace")

chatroom = ChatRoom(
    endpoint=endpoint,
    memory_dir="./chats"
)

From Team Instance

from pantheon.chatroom import ChatRoom
from pantheon.team import PantheonTeam
from pantheon.agent import Agent

agents = [
    Agent(name="researcher", instructions="..."),
    Agent(name="writer", instructions="...")
]

team = PantheonTeam(agents)
chatroom = ChatRoom(team=team)

Configuration

ChatRoom settings in .pantheon/settings.json:

{
  "chatroom": {
    "memory_dir": ".pantheon/memory",
    "enable_nats_streaming": false,
    "speech_to_text_model": null
  }
}

Options:

• memory_dir: Directory for conversation persistence

• enable_nats_streaming: Enable NATS for distributed deployment

• speech_to_text_model: Model for speech-to-text (if enabled)

Team Templates

ChatRoom uses team templates from .pantheon/teams/:

---
name: Data Analysis Team
icon: 📊
agents:
  - name: analyst
    model: openai/gpt-4o
    instructions: You analyze data and find insights.
    toolsets:
      - python_interpreter
      - file_manager
  - name: visualizer
    model: openai/gpt-4o
    instructions: You create visualizations.
    toolsets:
      - python_interpreter
---

# Data Analysis Team

A team specialized in data analysis and visualization.

See Team Templates for template format details.

NATS Streaming

For distributed deployments, enable NATS streaming:

{
  "chatroom": {
    "enable_nats_streaming": true
  },
  "remote": {
    "nats_url": "nats://localhost:4222"
  }
}

This allows:

• Multiple ChatRoom instances sharing state

• Remote toolset connections

• Distributed agent execution

API Endpoints

ChatRoom exposes these endpoints:

Endpoint	Description
/chat	Main chat WebSocket
/health	Health check
/info	Service information

Custom Integration

Embedding in Existing App

from fastapi import FastAPI
from pantheon.chatroom import ChatRoom

app = FastAPI()
chatroom = ChatRoom()

@app.on_event("startup")
async def startup():
    await chatroom.start()

@app.websocket("/chat")
async def websocket_endpoint(websocket):
    await chatroom.handle_websocket(websocket)

Event Hooks

class CustomChatRoom(ChatRoom):
    async def on_message(self, message):
        # Called when user sends a message
        print(f"User: {message}")
        return await super().on_message(message)

    async def on_response(self, response):
        # Called when agent responds
        print(f"Agent: {response}")
        return response

Monitoring

Logs

ChatRoom logs are written to:

• Console (configurable level)

• ~/.pantheon/logs/chatroom.log

Metrics

Track token usage and costs via the returned response metadata.

Security Considerations

API Keys

Never expose API keys in the UI. They should be:

• Set as environment variables on the server

• Configured in settings.json on the server

Workspace Isolation

Each ChatRoom has its own workspace. Files are isolated per session.

Network

• The ChatRoom server should be behind a firewall in production

• Use HTTPS for the UI connection

• Consider authentication for multi-user deployments