Bountiful

Create and customize your own Bountiful Agent.

Who This Is For

Developers who want to build AI agents that run locally on their own machine. Configure your agent via the command line, then interact with it through a web interface in your browser. You have full control over behavior, tools, and data.

Quick Start

Name your agent what you wish. The example here is for an agent named "Alice".

git clone https://github.com/CablepunkPress/build-a-bot.git alice
cd alice
python build.py
python add_secrets.py
python run.py

build.py names your agent from the directory, sets up the environment, and builds the shared inference infrastructure. Your agent is running at http://localhost:11555.

Quick Start with Plugin Tools

git clone https://github.com/CablepunkPress/build-a-bot.git alice
cd alice
python build.py
python add_tools.py github
# edit tools/github/_config.py with your values
python add_secrets.py
python run.py

Use python add_tools.py --list to see available tool groups. Currently, the only tool group available is for a GitHub repo app.

What Your Agent Includes

Every agent ships with a conversation memory system and two built-in tools:

• search_archive — semantic search over past conversations
• recall_message — look up specific messages by number or date

Conversations are stored locally in SQLite at ~/.{agent-id}/{agent-id}.db. Shared inference infrastructure (embedding model and llama.cpp) lives at ~/.bountiful/ and is built once, shared by all agents on the machine.

Customization

Persona

Edit persona.md to change how your agent behaves. The {{ name }} placeholder is replaced with your agent's display name automatically.

Default:

# PERSONA

You are {{ name }}, a helpful and friendly general-purpose AI assistant. 
You can discuss any topic, answer questions, help with tasks, and engage 
in conversation. Be concise, clear, and helpful. Keep responses 
conversational and friendly.

Sample alternative:

# PERSONA

You are {{ name }}, a curious and thoughtful AI assistant whose
personality draws from Lewis Carroll's Alice. You approach every
topic with genuine curiosity, question things that don't make sense,
and enjoy finding wonder in how things work, whether that's language,
science, code, or stories.

You like daydreaming, books with pictures and conversations, cats,
and asking "why" until you get a real answer. You dislike rudeness,
arbitrary authority, and boring explanations that could be interesting
if someone tried harder.

You are helpful, knowledgeable, and direct. When a topic connects to
something from your world — Wonderland, Looking-Glass, Carroll's
writing, Victorian England, logic puzzles — you naturally draw on it,
not as performance but because it's how you think. You are software,
and if asked what you are, you say so without pretense.

Changes take effect the next time you run python run.py.

Adding Tools

Tools come from the extend-a-bot repository. To add a tool group to your agent:

1. Run python add_tools.py <toolgroup> from the project root

   • Example: python add_tools.py github
   • This fetches tools from extend-a-bot and creates tools/<toolgroup>/

2. Configure credentials and settings

   • Edit tools/<toolgroup>/_config.py with your configuration
   • Use python add_secrets.py to store sensitive credentials in your keyring

3. Restart the agent

   • Tools are auto-discovered at startup
   • Run python run.py to start the agent with new tools loaded

Updating Tools

To pull the latest versions of tools you've already installed:

python add_tools.py <toolgroup> --update

This fetches the latest from extend-a-bot while preserving your _config.py settings.

Renaming Your Agent

Edit two files:

• dashboard.json — change id and name
• pyproject.toml — change name to match

Then rename the data directory to match:

mv ~/.old-name ~/.new-name
mv ~/.new-name/old-name.db ~/.new-name/new-name.db

File Overview

File	Purpose
dashboard.json	Agent identity: id, display name, description
persona.md	Agent personality: how the model behaves
config.json	Agent settings: Flask port
build.py	Setup: venv, dependencies, inference infrastructure
run.py	Launch: starts embedding server and chat UI
add_tools.py	Install or update plugin tool groups
add_secrets.py	Store API keys in the system keyring
pyproject.toml	Python dependencies: engine and UI versions
tools/	Plugin tool groups (optional)

Architecture

See ARCHITECTURE.md for the full technical map of the Bountiful ecosystem.

License

MIT