Reference¶

API — PersistentChatbot¶

from chatbot_agent import PersistentChatbot

Constructor¶

PersistentChatbot(db_path: str = "chatbot_memory.db", enable_sub_agents: bool = True, model: str = "qwen3:8b")

model sets the default Ollama model. Can be overridden per-call in respond().

Methods¶

Method	Description
`start_new_session(session_name)`	Create a new conversation session, returns `session_id`
`load_session(session_id)`	Load an existing session, returns `bool`
`save_message(role, content)`	Save a message (`"user"` or `"assistant"`) to current session
`get_conversation_history(session_id, limit)`	Get messages for a session
`list_sessions()`	List all sessions with message counts
`search_messages(query)`	Full-text search across all sessions
`respond(user_input, model=None)`	Generate and save a response; `model` overrides the instance default, returns `str`
`close()`	Close the database connection

Example¶

from chatbot_agent import PersistentChatbot

chatbot = PersistentChatbot("my_chatbot.db")
session_id = chatbot.start_new_session("My First Chat")

response = chatbot.respond("Hello!")
print(response)

history = chatbot.get_conversation_history()
for msg in history:
    print(f"{msg['role']}: {msg['content']}")

chatbot.close()

Database Schema¶

sessions¶

Column	Type	Description
`session_id`	INTEGER PK	Auto-increment primary key
`created_at`	TIMESTAMP	Session creation time
`last_active`	TIMESTAMP	Last message time
`session_name`	TEXT	Optional display name

messages¶

Column	Type	Description
`message_id`	INTEGER PK	Auto-increment primary key
`session_id`	INTEGER FK	References `sessions.session_id`
`role`	TEXT	`"user"` or `"assistant"`
`content`	TEXT	Message body
`timestamp`	TIMESTAMP	Message time

CLI Commands¶

When running python3 src/chatbot_agent.py interactively:

Command	Action
(any text)	Chat with the bot
`history`	Display full conversation history
`search <query>`	Search messages across all sessions
`quit` / `exit`	End session

Extending the Chatbot¶

Switch Ollama Model¶

Web UI: Use the model dropdown in the header — lists all installed Ollama models, switches per-message without restart.

Programmatic: Pass model to the constructor or to respond():

# Set a default for the whole session
chatbot = PersistentChatbot(model='llama3.2')

# Or override per-message
response = chatbot.respond("Hello!", model='gemma3:12b')

Run ollama list to see installed models, or browse ollama.ai/library.

Use a Cloud Provider¶

Replace _generate_response() in src/chatbot_agent.py:

OpenAIAnthropic Claude

import openai

def _generate_response(self, user_input, history):
    messages = [{"role": m['role'], "content": m['content']} for m in history]
    messages.append({"role": "user", "content": user_input})
    response = openai.chat.completions.create(model="gpt-4o", messages=messages)
    return response.choices[0].message.content

import anthropic

def _generate_response(self, user_input, history):
    client = anthropic.Anthropic()
    messages = [{"role": m['role'], "content": m['content']} for m in history]
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        messages=messages,
    )
    return response.content[0].text

Customize the System Prompt¶

Edit the system message in _generate_response:

system_content = 'You are a helpful coding assistant specialized in Python.'

Add RAG¶

Use search_messages to pull relevant context from past sessions:

relevant = self.search_messages(user_input)
context = "\n".join([f"{r['role']}: {r['content']}" for r in relevant[:5]])
# append context to system_content