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

# Cousins

> Working name - see [naming](#naming). A framework for running
> persistent AI agents ("cousins").

**Status:** `0.1.0`, pre-release. This repository is the *product cut*
of an existing household framework, being rebuilt clean - free of any
household, personal, or employer-specific material (see
[`docs/PERIMETER.md`](docs/PERIMETER.md)).

## What this is

A cousin is a long-lived AI agent with its own memory, identity, and
chat surface. The framework provides the machinery to spawn, run, and
maintain them. The original lives as a private household deployment;
this repo is the distributable, general-purpose extraction of it.

## Layout

```
src/cousins/      the package
tests/unit/       fast, isolated tests
tests/auto/       integration / end-to-end tests
docs/             architecture, contribution, perimeter policy
.github/workflows growth: CI
```

## Getting started

```sh
cousins init                 # lay out the runtime tree at a default root
cousins init --root ./demo   # ...or at a path you choose
cousins onboard --root ./demo/cousins   # guided setup for a new cousin
```

`cousins init` is idempotent - safe to re-run. `cousins onboard` asks a
handful of questions and scaffolds a cousin home with a validated
`cousin.toml`.

With Nix:

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

## Running the 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 version -v
```

Exit code is `0` when every test passes, `1` otherwise. CI runs the
same command across Python 3.11-3.13.

## Naming

"Cousins" is a working title carried over from the origin framework's
vocabulary. It is referenced only in `README.md`, `pyproject.toml`, and
`src/cousins/__init__.py`, so a rename is a three-file change.

## Roadmap

Tracked as the product-track items in the origin framework's backlog:
cross-platform installer, onboarding wizard, external chat channels,
provider abstraction, versioned releases, a sandbox run-mode toggle,
and public + internal documentation.
