cousins 0.2.5

A framework for running persistent AI agents.

Cousins

A framework for running persistent AI agents ("cousins").

A cousin is a long-lived AI agent with its own identity, memory, and chat surface — not a one-shot prompt, but an agent that persists across sessions and reboots. Cousins is the machinery to define, run, and maintain them.

Install

pip install cousins

Stdlib-only Python (3.11 or newer); no runtime third-party dependencies.

End-to-end: a Telegram bot driven by a local Ollama model

from cousins import client
from cousins.transports import OllamaTransport, TelegramBotTransport
from cousins.bridges.telegram import TelegramBridge
from cousins.chat import ClientBackend

c = client.build_client("ollama", transport=OllamaTransport(model="phi4-mini"))
bot = TelegramBotTransport(token="<your-bot-token>", poll_timeout=25)
bridge = TelegramBridge(bot=bot, backend=ClientBackend(c))

while True:
    bridge.poll_once()

That is a working LLM-on-Telegram bot in eight lines, against a local Ollama model with no API keys. See docs/site/bridges.md for the longer walkthrough (system prompts, error translation, persisting messages to the chat-server).

What ships today (v0.2.5)

• cousins CLI — init, onboard, run, serve-chat.
• Provider abstraction + LLM client — stable contract, capability enforcement, offline EchoTransport plus live transports.
• Live transports (cousins.transports):
  • OllamaTransport for a local Ollama HTTP server (no credential).
  • TelegramBotTransport for the Telegram Bot API.
• Telegram bridge (cousins.bridges.telegram) — normalises updates, routes them through a ChatBackend, handles long-poll offsets.
• Chat package (cousins.chat):
  • Store — sqlite-backed per-cousin message log.
  • Server — stdlib threading HTTP server with on_inbound / on_outbound host-seam callbacks.
  • EchoBackend + ClientBackend — concrete bridge backends.
• Configuration — strict cousin.toml schema with [sandbox] modes (host / systemd / container).
• Onboarding wizard — guided first-cousin scaffold; writes a validated cousin.toml, memory/, an AGENTS.md stub, and a .env.example template when the provider needs credentials.
• Runtime layout — platform-appropriate install root (Windows %APPDATA%, macOS Application Support, XDG on Linux).
• Releases — SemVer, Keep-a-Changelog cadence, GitHub Releases with attached sdist + wheel.

Layout

src/cousins/              the package
  ├─ bridges/             channel adapters (telegram)
  ├─ chat/                store + HTTP server + bridge backends
  ├─ providers/           provider abstraction
  ├─ transports/          live network-backed transports
  ├─ client.py            LLM client + Transport seam
  ├─ config.py            cousin.toml load + validate
  ├─ layout.py            runtime directory layout
  ├─ onboarding.py        cousins onboard wizard
  ├─ run.py               cousins run handler
  ├─ runtime.py           sandbox-mode launch artifact rendering
  └─ version.py           SemVer 2.0.0
tests/unit/               fast, isolated tests
tests/auto/               integration / end-to-end tests
docs/                     architecture, contribution, site, perimeter policy
.github/workflows/        CI

Getting started

cousins init                          # runtime layout at a default root
cousins onboard --root ./cousins      # guided setup for a new cousin
cousins serve-chat <slug> --root ./cousins   # foreground chat HTTP server

With Nix:

nix build          # build the package
nix develop        # dev shell
nix flake check    # run the test suite in a sandbox

Tests

No dependencies, no pytest — stdlib only:

python3 -m tests._runner            # everything
python3 -m tests._runner unit       # only unit tests
python3 -m tests._runner --filter chat -v

CI runs the same command across Python 3.11–3.13. Live integration tests against real backends are gated behind environment variables:

COUSINS_LIVE_OLLAMA=1 python3 -m tests._runner unit --filter ollama
COUSINS_LIVE_TELEGRAM=1 COUSINS_TELEGRAM_BOT_TOKEN=... \
    python3 -m tests._runner unit --filter telegram

Roadmap

Tracked as the product-track items in the origin framework's backlog. What's deferred from v0.2.x:

• Anthropic and OpenAI live transports (gated on credentials to verify against).
• Host-style chat-server features (tmux fan-out, static file serving, agent-log endpoints) — the host wires its own glue via on_inbound / on_outbound seams today.
• The full cousin lifecycle (spawn / flip / transplant / reincarnate), memory layers, hooks and scheduling — migrating in from the origin framework.

Documentation

• Site index
• Install
• Concepts
• Bridges
• CLI reference
• Architecture
• Perimeter policy
• Contributing

License

See LICENSE.