Metadata-Version: 2.5
Name: brian-core
Version: 2.0.0rc32
Summary: A provider-neutral, fault-tolerant agent runtime
Author: TTG AI LLC
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.11
Requires-Dist: anthropic<1,>=0.50.0
Requires-Dist: apscheduler<4,>=3.10.0
Requires-Dist: coverage<8,>=7.15.0
Requires-Dist: ddgs<10,>=9.0.0
Requires-Dist: fastapi<1,>=0.138.1
Requires-Dist: fastembed<1,>=0.8.0
Requires-Dist: httpx<1,>=0.27.0
Requires-Dist: mcp<2,>=1.27
Requires-Dist: openai<3,>=2.0.0
Requires-Dist: openpyxl<4,>=3.1.0
Requires-Dist: opentelemetry-api<2,>=1.38.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.38.0
Requires-Dist: opentelemetry-sdk<2,>=1.38.0
Requires-Dist: paramiko<6,>=3.4.0
Requires-Dist: playwright<2,>=1.49.0
Requires-Dist: prompt-toolkit<4,>=3.0.52
Requires-Dist: pydantic-settings<3,>=2.0.0
Requires-Dist: pymongo<5,>=4.6.0
Requires-Dist: pymupdf<2,>=1.24.0
Requires-Dist: pytesseract<1,>=0.3.13
Requires-Dist: python-docx<2,>=1.1.0
Requires-Dist: python-pptx<2,>=1.0.0
Requires-Dist: rich<16,>=15.0.0
Requires-Dist: sqlalchemy<3,>=2.0.0
Requires-Dist: tavily-python<1,>=0.5.0
Requires-Dist: textual<9,>=8.0.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: uvicorn[standard]<1,>=0.49.0
Provides-Extra: desktop
Requires-Dist: mss<11,>=9.0.1; extra == 'desktop'
Requires-Dist: pyautogui<1,>=0.9.54; extra == 'desktop'
Provides-Extra: hosted
Requires-Dist: psycopg[binary]<4,>=3.2.0; extra == 'hosted'
Provides-Extra: providers
Requires-Dist: boto3<2,>=1.42.0; extra == 'providers'
Requires-Dist: google-genai<3,>=1.56.0; extra == 'providers'
Description-Content-Type: text/markdown

<div align="center">

<img src="https://raw.githubusercontent.com/mrgizmo212/Brian/main/docs/assets/brian.png" alt="BRIAN" width="140" style="border-radius: 28px;">

# BRIAN

**A self-hosted agent runtime.** Model, loop, tools, memory, permissions.

[![PyPI](https://img.shields.io/pypi/v/brian-core)](https://pypi.org/project/brian-core/)
[![Python](https://img.shields.io/pypi/pyversions/brian-core)](https://pypi.org/project/brian-core/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

`pip`-installable as **`brian-core`** `2.0.0rc32`. The command is **`brian`**.

</div>

**macOS / Linux**

```bash
curl -fsSL https://heybrian.ai/install | bash
```

**cmd**

```
powershell -c "irm https://heybrian.ai/install.ps1 | iex"
```

**PowerShell**

```powershell
irm https://heybrian.ai/install.ps1 | iex
```

First `brian` in a terminal asks for a provider, credentials, and model, seeds `~/.brian/SOUL.md` if missing, live-pings the provider, then asks what to call you. `brian doctor` diagnoses the home without starting a session. Pipe install stays non-interactive. Bring your own LLM key. The wheel is code — memory and sessions start empty, in `~/.brian`.

## What you get

| Door | How |
|---|---|
| CLI | `brian` |
| HTTP API | `brian --api` |
| Agent SDK | `from brian_core.sdk import run` — same loop, in-process, not HTTP |

`BrianClient` talks to the HTTP API. It is not the Agent SDK.

```python
from brian_core.sdk import run, stream

print(run("list python files"))
for event in stream("list python files"):
    ...
```

Twelve providers (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, DeepSeek, Mistral, xAI, Ollama, LM Studio, plus generic gateways). Seventy tools: shell, files, browser, desktop, web, media, MCP, subagents, durable runs that survive a crash.

## From this repo

Git, Python 3.11+, [uv](https://docs.astral.sh/uv/). Code lives under `src/brian_core`.

```bash
git clone https://github.com/mrgizmo212/Brian.git
cd Brian
uv sync
uv run brian --help
uv run brian
uv run brian "list python files"
```

Optional extras: `providers`, `hosted`, `desktop` (screen control).

## Modes

```bash
uv run brian                         # TUI
uv run brian --repl                  # CLI prompt
uv run brian "do this"               # one shot
uv run brian --continue              # last session
uv run brian --resume <session-id>
uv run brian --fork-session <id>
uv run brian --tui
uv run brian --api
uv run brian --scheduler
uv run brian --heartbeat-only
uv run brian --learning-graph
uv run brian --version
uv run brian doctor
```

One mode per invocation. `--api` requires `API_SERVER_KEY`.

## HTTP API

```bash
uv run brian --api
curl -fsS http://127.0.0.1:8000/health
curl -fsS http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer $API_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agent","messages":[{"role":"user","content":"Say hello."}]}'
```

| Endpoint | Purpose |
|---|---|
| `POST /v1/chat/completions` | Chat, streaming or not |
| `POST /v1/responses` | Responses API, streaming or not; chain turns with `previous_response_id` |
| `GET /v1/responses/{id}` / `DELETE /v1/responses/{id}` | Fetch or delete a stored response |
| `POST /v1/runs` | Durable run |
| `GET /v1/runs/{id}/events` | SSE |
| `POST /v1/runs/{id}/approval` | Human approval |
| `GET /v2/capabilities` | Machine-readable surface |

Self-host with Docker: [`deploy/README.md`](deploy/README.md).

## Bring your own machine

Let heybrian chats run `bash`, file reads/writes/edits, `undo`, `glob` and `grep` on your own
laptop or server, inside an OS sandbox limited to the folders you choose. The helper only
connects **out** to heybrian over HTTPS; nothing listens on your machine. Your admin turns it on
in Admin → Configuration → `machines.enabled`.

Command output streams live to the chat while a command runs. When a command stops to ask a
question ("Overwrite? (y/n)"), you answer it on the question card in the chat.

Install, pair once, then start the helper:

```bash
# macOS
brew install pipx && pipx install 'brian-core[desktop]==2.0.0rc32'
# Linux
sudo apt install -y bubblewrap pipx && pipx install 'brian-core==2.0.0rc32'
# Windows (PowerShell) — also follow srt's one-time restricted-account setup
py -m pip install --user pipx; py -m pipx install 'brian-core==2.0.0rc32'; npm install -g @anthropic-ai/sandbox-runtime

brian pair                                  # shows a code; enter it in heybrian → Settings → BRIAN → Your machines
brian worker --dir ~/code/project           # add more --dir flags for more folders (max 16)
brian machine status                        # pairing, sandbox and git token state
brian machine unpair                        # delete the local credential (also: brian unpair)
```

| Flag | Meaning |
|---|---|
| `--dir PATH` | A folder BRIAN may work in. Not `/`, not your whole home folder. |
| `--allow-network` | Commands may use the network (off by default). |
| `--allow-domain DOMAIN` | Only these domains (srt only; with bubblewrap or sandbox-exec it allows all network and says so). |
| `--screen` | Let BRIAN's `computer` tool act on this screen (needs the `desktop` extra). |
| `--git-email-domain DOMAIN` | Domain for agent commit emails (default `users.noreply.heybrian.ai`). |
| `--url URL` | heybrian address (default `https://heybrian.ai`). |

**Sandbox.** Every command runs in `srt` (Anthropic sandbox-runtime) when it is on `PATH`, otherwise
`bwrap` on Linux or `sandbox-exec` on macOS. Windows needs `srt`. With none of them the helper
exits with code 4 and never runs a command unsandboxed. Commands can write only to your folders
and a private scratch dir, cannot read the rest of your home folder or the helper's credential
folder, cannot open Unix sockets (Linux), and have no network unless you allow it. File reads,
writes and edits run in the helper itself, confined to the folders (`..`, absolute paths and
symlinks that leave a folder are refused). Every write keeps an undo snapshot under the helper's
folder.

**Screen control** (`--screen`, off by default, and only when your admin enabled
`machines.screenControl.enabled`). You grant each app in Settings → Your machines as full,
click-only or view-only; apps you have not granted are refused, and password managers are always
view-only. Every screen action asks you first unless you turn on "Let BRIAN act without asking".
BRIAN refuses to type into password, sign-in and payment windows or password fields, and never
types card numbers. Move the pointer to the top-left corner to stop it at once. On macOS grant
Screen Recording and Accessibility to your terminal in System Settings → Privacy & Security; on
Linux an X11 session with `xdotool` is needed (Wayland is not supported).

**Git identity.** Commits made on the machine carry the agent's name as `<agent> (BRIAN)` and
`<agent>+brian@users.noreply.heybrian.ai`. To let BRIAN push, store a token locally
(`brian machine git-token set`, read from stdin, never from the command line; `clear` removes it).
It is saved as `git-token` (mode 0600) next to `machine.json`, handed to git through a
per-command credential helper, never sent to heybrian or the model, and masked as `***` in every
output. Pushing also needs network, e.g. `--allow-domain github.com`.

Files: `~/.config/brian/machine.json` (macOS/Linux) or `%APPDATA%\brian\machine.json` (Windows),
mode 0600; `BRIAN_MACHINE_HOME` overrides the folder. Exit codes: 0 ok, 2 not paired, 3 removed in
heybrian (the credential is deleted), 4 no OS sandbox, 5 turned off by your admin.

## Config

Settings live in `~/.brian/.env` (or `BRIAN_ENV_FILE`). Names are in [`env.example`](env.example). Required: `PROVIDER`, `MODEL`, and that provider's key.

Override the home directory with `BRIAN_HOME`.

## Docs

- [`docs/CAPABILITIES.md`](docs/CAPABILITIES.md) — what it can do (Memory Trio: flush-before-compact, stub summary, skill proposals; Engine parity 2026-09-20: real token counting, file-tool fence, default step cap, one durable path, surfaced transcript failures, CI)
- [`docs/brian-operator.md`](docs/brian-operator.md) — SOUL, skills, MCP, session save, compaction flags
- [`AGENTS.md`](AGENTS.md) — working in this repo (module index, Memory Trio table, Engine parity table)
- [`docs/core-v2/package-migration.md`](docs/core-v2/package-migration.md) — package, CLI, and install reference

## License

MIT License. Copyright 2026 TTG AI LLC. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).
