Metadata-Version: 2.4
Name: maestro-care
Version: 0.0.1
Summary: Collaborative Agent Reasoning Ecosystem — Textual TUI demo
Project-URL: Homepage, https://github.com/AIRI-Institute/care
Project-URL: Repository, https://github.com/AIRI-Institute/care
Project-URL: Issues, https://github.com/AIRI-Institute/care/issues
Keywords: agents,care,carl,evolution,llm,mage,textual,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Terminals
Requires-Python: >=3.12
Requires-Dist: gigaevo-client>=0.3.0
Requires-Dist: httpx>=0.27
Requires-Dist: mmar-mage>=0.1
Requires-Dist: pydantic>=2.11
Requires-Dist: pypdf>=4.0
Requires-Dist: python-pptx>=0.6.21
Requires-Dist: rich-pixels>=3.0
Requires-Dist: textual>=8.2.6
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == 'anthropic'
Provides-Extra: carl
Requires-Dist: mmar-carl>=0.2; extra == 'carl'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: docker
Requires-Dist: docker>=7.0; extra == 'docker'
Provides-Extra: e2b
Requires-Dist: e2b>=0.17; extra == 'e2b'
Provides-Extra: full
Requires-Dist: anthropic>=0.20; extra == 'full'
Requires-Dist: docker>=7.0; extra == 'full'
Requires-Dist: e2b>=0.17; extra == 'full'
Requires-Dist: mmar-carl>=0.2; extra == 'full'
Requires-Dist: openai>=1.0; extra == 'full'
Requires-Dist: plotext>=5.2; extra == 'full'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Provides-Extra: plots
Requires-Dist: plotext>=5.2; extra == 'plots'
Description-Content-Type: text/markdown

# CARE — Collaborative Agent Reasoning Ecosystem

A Textual TUI + CLI for generating, running, and evolving CARL agent
chains. CARE is the user-facing consumer on top of a four-module stack —
**MAGE** for chain generation, **CARL** for execution, **GigaEvo Memory**
for persistence, and **GigaEvo Platform** for evolution.

## Run

```bash
uv sync
uv run care init       # one-shot: write a minimal .env with MAGE creds
uv run care            # launch the TUI
uv run care --help     # list CLI subcommands
```

`care init` walks the minimum MAGE credentials (base URL, API key,
model) and writes a `./.env` so a fresh checkout can boot. Use
`--non-interactive` with explicit flags for CI / scripted setup:
`care init --non-interactive --api-key sk-... --base-url ... --model ...`.

The TUI opens directly into the **chat surface** — a Claude-Code-style
transcript with a prompt at the bottom and a mode toggle above it.
Type a task in natural language to generate + run an agent chain;
type a slash command (`/help`, `/mode`, `/library`, `/dataset`,
`/evolution`, `/tour`, …) for the non-chat affordances. First-time
users see a one-line offer to type `/tour` for a 5-step walkthrough.

### Chat modes

The toggle above the prompt picks one of two modes; `/mode` switches
the same setting via the keyboard. Default is **Ad-Hoc** —
configurable per-deployment with `CARE_CHAT__DEFAULT_MODE`.

| Mode           | What happens on every prompt                                                                                                                                                                                                                                                                         |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ad-Hoc**     | MAGE generates a chain, CARL runs it on the spot, the answer prints inline. The agent may loop (ReAct) until it decides the task is done. **Nothing is saved.**                                                                                                                                      |
| **Production** | MAGE generates a _reproducible_ chain, CARE saves it to Memory under a stable `chain_id`, runs one baseline to seed a dataset entry, and (when Platform is wired) kicks off an evolution run. Use `/dataset list <chain_id>` / `/dataset run <chain_id>` / `/evolution watch <run_id>` to follow up. |

Production requires `CARE_MEMORY__BASE_URL` (and `CARE_MEMORY__API_KEY`
when the deployment enforces auth). Without Memory configured,
selecting Production auto-falls back to Ad-Hoc with a warning line —
the toggle's tooltip explains why.

First boot (no `~/.config/care/config.toml` on disk) lands on the
**Settings** screen so you can configure Memory / Platform base URLs +
the MAGE LLM credentials before doing anything else. Returning users
land on the chat surface; `/library` opens the saved-agents table
(last-run time, favourite status, fitness scores, row-action keys
below).

## Canonical user flow

Generate Agent A → save it → generate B and C → return to A from the
library → re-run from the same task + context files → optionally
evolve A and accept the best individual back into the stable channel.

## Screens

CARE ships **18+ screens** covering the full lifecycle:

| Screen                | Purpose                                          |
| --------------------- | ------------------------------------------------ |
| `WelcomeScreen`       | Boot splash + recents sidebar                    |
| `LibraryScreen`       | Saved-agent table, row actions, search           |
| `QueryScreen`         | + New agent — task description + context files   |
| `GenerationScreen`    | Live MAGE progress                               |
| `InspectionScreen`    | Saved-chain detail + run history                 |
| `EditAgentScreen`     | Inline edit + Save / Promote-to-stable           |
| `ExecutionScreen`     | Live CARL run + token streaming                  |
| `EvolutionScreen`     | GA + Pareto picker + accept-winner               |
| `ReplayScreen`        | Step through a saved ReasoningResult             |
| `CatalogScreen`       | Browse installed capabilities (skills/MCP/tools) |
| `MarketplaceScreen`   | Search shared agent_skill listings on Memory     |
| `HelpScreen`          | Tutorial + key cheat-sheet                       |
| `SettingsScreen`      | Edit MAGE / Memory / Platform / theme            |
| `TaskListDrawer`      | In-flight tasks panel                            |
| `CommandPaletteModal` | Fuzzy palette over commands + saved entities     |
| `DiffModal`           | Side-by-side compare two chains                  |
| `LineageModal`        | Walk a chain's ancestry DAG                      |
| `ConflictModal`       | Resolve a name collision on save                 |

## Global keys

- `Ctrl+P` — Command palette (search commands + chains + skills)
- `Ctrl+B` — Task list drawer
- `Ctrl+K` — Capability catalog
- `Ctrl+S` — Save current artifact
- `Ctrl+R` — Re-run current chain
- `?` — Help (tutorial + every binding)
- `Esc` — Back / cancel
- `Ctrl+Q` — Quit

Each screen layers its own bindings — see `?` (Help) for the full set
filtered by the active screen.

A single-page reference table covering every screen + modal lives at
[`docs/screens/README.md`](docs/screens/README.md). It maps each
surface to its slash command + status (M0/M1) + primary purpose so a
new contributor can locate the right module from one click.

## Demo

A short asciicast walks the three CLI surfaces against a
hermetic seed directory. Reproduce or re-record with:

```bash
scripts/record_demo.sh
```

See [`examples/asciicast/recording_script.md`](examples/asciicast/recording_script.md)
for the per-act keystroke list. The output lands at
`docs/asciicasts/care-tour.cast` and can be embedded in this
README once recorded (`asciinema upload` for a hosted player or
a local relative link for offline reading).

## Architecture

CARE is the consumer at the top of a four-module stack — see
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the layer-by-layer
walk-through (generation / execution / persistence / evolution) with
cross-links to the upstream modules and CARE's internal module
boundaries.

## Configuration

CARE reads its configuration from three sources, in increasing precedence:

1. Defaults baked into `care.config.CareConfig`.
2. `~/.config/care/config.toml` (user-global TOML).
3. `./care.toml` in the current working directory (per-project overrides).
4. `CARE_*` environment variables.

Nested fields use double-underscores in env-var form, mirroring how the
TOML sections nest. For example, `[mage] mode = "fast"` in TOML is
`CARE_MAGE__MODE=fast` in the environment.

See [`.env.example`](.env.example) for the complete list of supported
variables with descriptions and defaults. Copy it to `.env` (or export the
vars in your shell) and override only what you need.

### Quick reference

| Section     | Env-var prefix      | Purpose                                |
| ----------- | ------------------- | -------------------------------------- |
| `mage`      | `CARE_MAGE__*`      | MAGE generator (provider, API key, …)  |
| `memory`    | `CARE_MEMORY__*`    | GigaEvo Memory connection              |
| `platform`  | `CARE_PLATFORM__*`  | GigaEvo Platform connection            |
| `sandbox`   | `CARE_SANDBOX__*`   | AgentSkill sandbox backend + limits    |
| `tools`     | `CARE_TOOLS__*`     | `@carl_tool` registry + bundled builtins (web_search, …) + on-the-fly synthesis |
| `telemetry` | `CARE_TELEMETRY__*` | Opt-in event-stream sink (Langfuse, …) |
| `defaults`  | `CARE_DEFAULTS__*`  | UI defaults (language, history size)   |

## CLI

`care` (no subcommand) launches the TUI. The headless subcommands share
the `CareConfig` and data layers the TUI uses — every screen's primary
affordance has a terminal twin.

**Setup**

- `care init [--non-interactive] [--api-key X] [--base-url Y] [--model Z] [--mode ad_hoc|production] [--force]` —
  one-shot quick-start: writes a minimal `.env` with the four MAGE +
  chat keys a fresh checkout needs. Refuses to overwrite an existing
  `.env` without `--force`.

**Discovery & validation**

- `care catalog [--json] [--kind ...]` — list installed AgentSkills,
  MCP servers, tools, capability memory cards.
- `care validate <chain.json>` — parse + preflight a CARL chain.
- `care import <pattern>... [--apply]` — batch-validate (dry-run
  default) or import chain JSON files.

**Generate / run / replay**

- `care generate "<task>" [--mode fast|deep] [--save NAME] [--output PATH]` —
  one-shot MAGE generation.
- `care run <chain_id> [--execute] [--task TEXT] [--input KEY=VAL] [--save-result NAME]` —
  fetch a saved chain, preflight, and optionally execute via CARL.
- `care replay <run.json>` — step through a saved
  `ReasoningResult` / `RunRecord` JSON.

**Memory browse**

- `care memory ls [--entity-type ...] [--tag ...] [--q ...]` —
  list saved entities.
- `care memory show <entity_id> [--content-only]` — drill down on
  a single entity.
- `care memory history <chain_id>` — list recorded runs for a
  chain.
- `care search "<query>" [--search-type bm25|vector|hybrid]` —
  BM25 / vector / hybrid search across saved entities.
- `care diff <left_id> <right_id>` — side-by-side chain compare.
- `care lineage <chain_id>` — walk the ancestry DAG.
- `care favourite <entity_id> [--off]` — star / unstar a library
  entity.

**Capabilities & evolution**

- `care marketplace "<query>"` — search shared agent_skill listings.
- `care evolve <chain_id> [--wait] [--accept]` — submit + watch +
  accept an evolution run.

**UX**

- `care help [--markdown]` — render the tutorial + cheat-sheet.

Run `care <subcommand> --help` for the full flag set on each.
