Metadata-Version: 2.4
Name: cousins
Version: 0.2.10
Summary: A framework for running persistent AI agents.
Author-email: Jhonata Poma-Hansen <jhonata.poma@gmail.com>
License: TBD
Project-URL: Homepage, https://github.com/bomba5/cousins-framework
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Cousins

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

[![PyPI](https://img.shields.io/pypi/v/cousins.svg)](https://pypi.org/project/cousins/)
[![Python](https://img.shields.io/pypi/pyversions/cousins.svg)](https://pypi.org/project/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

```sh
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

```python
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`](docs/site/bridges.md)
for the longer walkthrough (system prompts, error translation,
persisting messages to the chat-server).

## What ships today (v0.2.10)

- **`cousins` CLI** — `init`, `onboard`, `run`, `launch`, `memory`,
  `serve-chat`.
- **Provider abstraction + LLM client** — stable contract, capability
  enforcement, offline `EchoTransport` plus live transports.
- **Live transports** (`cousins.transports`):
  - `AnthropicCCTransport` drives the locally-installed `claude` CLI
    (Claude Code), reusing its auth — subscription OAuth, API key, or
    Bedrock — so no `ANTHROPIC_API_KEY` is required for subscription
    users.
  - `OllamaTransport` for a local Ollama HTTP server (no credential).
  - `TelegramBotTransport` for the Telegram Bot API.
- **Memory layer.** `cousins run` assembles a boot context per
  invocation (cousin role + `memory.for_boot_packet` distilled +
  active raw + the last 20 turns of the CLI chat-store transcript),
  prepends it to the system prompt, and persists each turn to the
  chat store so the next invocation picks up where it left off.
- **`cousins memory <slug> {list,add,boot-packet}`** — inspect and
  add to a cousin's durable memory from the CLI; preview exactly
  what the run loop would inject into the system prompt.
- **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

```sh
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:

```sh
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:

```sh
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:

```sh
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](docs/site/index.md)
- [Install](docs/site/install.md)
- [Concepts](docs/site/concepts.md)
- [Bridges](docs/site/bridges.md)
- [CLI reference](docs/site/cli.md)
- [Architecture](docs/architecture.md)
- [Perimeter policy](docs/PERIMETER.md)
- [Contributing](CONTRIBUTING.md)

## License

See `LICENSE`.
