bob (0.9.8)

Published 2026-02-20 20:17:03 +00:00 by ahknight

To install the package using pip, run the following command:

pip install --index-url  --extra-index-url https://pypi.org/simple bob

For more information on the PyPI registry, see the documentation.

Bob: A cognitive architecture daemon

Bob

"I wanted to see what happened"

Bob is a cognitive architecture daemon — a research sandbox exploring emergent behavior through memory, attention, and self-modification capabilities. His mind is a git repository of Markdown files; learning is literally a git commit.

For architecture details, see docs/internals/. For configuration reference, see docs/configuration.md. For common issues, see docs/troubleshooting.md.

Prerequisites

Python 3.12+
uv (package manager)
Ollama (optional, for local models)
A Discord bot token (optional, for Discord integration)
An OpenRouter or Anthropic API key (for remote models)

Quick Start

# Clone and install
git clone <repo-url> && cd bob
uv sync

# Initialize Bob's mind (first time only)
cd data && git init && git add . && git commit -m "Birth" && cd ..

# Set environment variables (see table below)
# Create .env with your keys (see Environment Variables below)

# Run Bob
uv run bob
# or: uv run python -m src.main

Container Quick Start

# Set environment variables in .env, then either:
docker compose up
# or
podman compose up

The dashboard is available at http://localhost:8080. When running in Docker, Ollama on the host is reached via host.docker.internal:11434 by default.

Environment Variables

Variable	Required	Description
`DISCORD_BOT_TOKEN`	For Discord	Discord bot token
`OPENROUTER_API_KEY`	For remote models via OpenRouter	OpenRouter API key
`ANTHROPIC_API_KEY`	For remote models via Anthropic	Anthropic API key
`OLLAMA_HOST`	No	Ollama server URL (default: `http://localhost:11434`)

Testing

# All tests
uv run pytest

# Unit tests only (no external services)
uv run pytest -m "not integration" -v

# Integration tests (requires Ollama)
uv run pytest -m integration -v

# Coverage
uv run pytest --cov=src --cov-report=html

# Lint and type check
uv run ruff check src/
uv run mypy src/

Architecture at a Glance

Metabolism — Energy, Curiosity, Tired counters that create organic rhythms
Inner Loop — Priority-based processing: survival → metabolism → events → monologue
Memory — Git-backed Markdown files with YAML frontmatter and WikiLinks
Attention — Self-modifiable YAML rules that filter and prioritize inputs
Model Router — LiteLLM-based routing to local (Ollama) or remote (OpenRouter/Anthropic) models by task type

bob/
├── src/
│   ├── core/        # EventBus, Metabolism, Librarian, ModelRouter
│   ├── agents/      # Chat, Monologue, Consolidation
│   ├── tools/       # Tool categories (self, concept, conversation, …)
│   └── interfaces/  # Dashboard (NiceGUI), Discord
├── tests/
└── data/            # Bob's mind (separate git repo)
    ├── config/      # YAML configuration files
    └── memory/      # Markdown knowledge files

Philosophy

Truth is Text — if it isn't in a Markdown file, Bob doesn't know it
Learning is Committing — memory consolidation is a git commit
Plasticity — anyone can edit any memory or rule directly; git revert for recovery

Requires Python: >=3.12

Details

PyPI

2026-02-20 20:17:03 +00:00

2

1.4 MiB

Assets (2)

bob-0.9.8-py3-none-any.whl 327 KiB

bob-0.9.8.tar.gz 1.0 MiB

Versions (6) View all

0.9.8

2026-02-20

0.9.7

2026-02-20

0.9.1

2026-02-16

0.9.0

2026-02-16

0.8.0

2026-02-15