Metadata-Version: 2.4
Name: probiotic
Version: 0.3.9
Summary: Autonomous self-improving agent framework for code repositories
Project-URL: Homepage, https://github.com/penthoy/probiotic
Project-URL: Repository, https://github.com/penthoy/probiotic
Project-URL: Issues, https://github.com/penthoy/probiotic/issues
Project-URL: Documentation, https://github.com/penthoy/probiotic/tree/main/docs
Project-URL: Changelog, https://github.com/penthoy/probiotic/blob/main/CHANGELOG.md
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,automation,cli,symbiont
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: hive-server
Requires-Dist: fastapi>=0.110; extra == 'hive-server'
Requires-Dist: uvicorn>=0.30; extra == 'hive-server'
Description-Content-Type: text/markdown

# Probiotic

Probiotic is an alpha runtime for repository-local autonomous agents. It
creates host-owned cells under `symbiont/cells/`, schedules them, and launches
a configured Codex, Claude Code, Kilo, or custom CLI.

## Security warning

Probiotic executes unattended agents with the permissions of the user running
it. Its built-in backends use unattended approval modes:

- Codex: `--dangerously-bypass-approvals-and-sandbox`
- Claude Code: `--dangerously-skip-permissions`
- Kilo: `--auto`

Run it only in repositories and operating-system accounts where that execution
model is acceptable. Hive jobs are remote code execution by design; prompt
updates can change later agent behavior. Both are disabled by default.

## Requirements

- Python 3.11 or newer
- At least one authenticated agent CLI: Codex, Claude Code, or Kilo
- `cron` only when using the scheduler/worker installers

Install Probiotic separately from the repository it manages:

```bash
uv tool install probiotic
# or: pipx install probiotic
```

## Quick start

From the repository that should host the cells:

```bash
probiotic init
probiotic status
probiotic run manager --dry-run
probiotic run manager
```

`probiotic init` creates a private, host-local `symbiont/config.toml` with mode
`0600`. The generated `symbiont/.gitignore` excludes that file, run logs,
history, locks, and prompt backups. Cell prompts, memory, journals, and tickets
remain repository-owned and may be committed deliberately.

Add narrowly scoped cells as needed:

```bash
probiotic spawn janitor
probiotic spawn documentation
probiotic run-nightly --dry-run
```

The default timezone is UTC. Budget limits in `config.toml` are absolute local
five-hour token ceilings; they are velocity signals, not provider billing or
subscription limits.

## Hive is optional

Hive provides shared reporting, prompt distribution, a dashboard, and remote
jobs. It is dormant until `connect-hive` is run, and its sensitive capabilities
remain opt-in after connection.

Connect with an API key supplied by the service environment:

```bash
export PROBIOTIC_HIVE_API_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
probiotic connect-hive https://hive.example.com
```

For a persistent local key without placing it in shell history:

```bash
probiotic connect-hive https://hive.example.com --api-key-file /secure/path/hive.key
```

`--api-key` remains for compatibility but is discouraged because command-line
arguments may be recorded in shell history and process listings. A key stored
by the CLI lives in the ignored, permission-restricted host config.

### Privacy and control defaults

| Capability | Default | Opt-in setting |
| --- | --- | --- |
| Basic heartbeat and cell state | On when Hive is connected | `symbiont.hive.enabled` |
| Upload agent/SOUL documents | Off | `symbiont.hive.share_prompts = true` |
| Upload approval rates | Off | `symbiont.hive.share_approval_rates = true` |
| Upload local model catalog | Off | `symbiont.hive.share_model_catalog = true` |
| Report a cell run | Off | `cell.hive_report = true` |
| Apply prompt updates | Off | `cell.hive_accept_improvements = true` |
| Accept remote jobs | Off | `symbiont.worker.accept_jobs = true` |

Heartbeats always include the instance ID, repository label, hostname,
Probiotic version, and basic enabled/backend/model cell state. Prompt/SOUL
contents are included only when `share_prompts` is explicitly enabled.

To accept remote jobs, first set `accept_jobs = true`, review the security
warning above, and then install the worker:

```bash
probiotic install-worker
```

### Keeping a node current

`probiotic update` upgrades the installed package from PyPI and then syncs the
node with the Hive — pending directives, accepted prompt improvements, and a
fresh heartbeat so the dashboard reports the new version:

```bash
probiotic update
probiotic update --dry-run       # report what would change
probiotic update --skip-upgrade  # sync only
```

The upgrade uses whichever installer owns this Probiotic (`uv tool`, `pipx`, or
`pip`), detected from the running interpreter. Once the package changes, the
sync half re-runs in a fresh process so it executes the new code.

Two cases are skipped deliberately: an editable checkout is never replaced with
a release wheel, and self-host mode refuses unless `--force`, so a routine
update cannot swap the code under a running Hive server. A node with no Hive
connection just performs the upgrade, which is the usual order on a new host:

```bash
uv tool install probiotic
probiotic init
probiotic update
probiotic connect-hive http://<host>:8000
```

### Server authentication

Protected Hive routes fail closed unless either `PROBIOTIC_HIVE_API_KEY` or
`PROBIOTIC_HIVE_TRUSTED_NETWORKS` is configured. Trusted networks may access
symbiont-level routes without a bearer key, but never satisfy the admin gate.
Job creation, directives, and template changes always require
`PROBIOTIC_HIVE_ADMIN_KEY`, falling back to `PROBIOTIC_HIVE_API_KEY` when an
explicit admin key is absent.

```bash
PROBIOTIC_HIVE_API_KEY=<symbiont-key>
PROBIOTIC_HIVE_ADMIN_KEY=<separate-admin-key>
PROBIOTIC_HIVE_TRUSTED_NETWORKS=10.10.0.0/24
```

Use TLS for bearer keys. Behind a reverse proxy, configure
`PROBIOTIC_HIVE_TRUSTED_PROXIES` and disable Uvicorn's own proxy-header
rewriting so Hive owns the trust decision:

```bash
PROBIOTIC_HIVE_TRUSTED_PROXIES=127.0.0.1/32 \
uvicorn probiotic.hive.server:app --host 127.0.0.1 --port 8000 --no-proxy-headers
```

The included `start_hive.sh` uses safe loopback binding by default and refuses
to start without API-key or trusted-network authentication.

Optional cost estimates and Claude model discovery can use a compatible
PostgREST catalog only when both `PROBIOTIC_PRICING_URL` and
`PROBIOTIC_PRICING_API_KEY` are set. No pricing service is contacted by
default. Local Hive-host Codex model discovery is likewise disabled unless
`PROBIOTIC_HIVE_DISCOVER_LOCAL_MODELS=true` is set.

## Local usage inspection

`probiotic usage` and budget-aware scheduling inspect local Codex usage from
`~/.codex/state_5.sqlite` and Claude Code usage from
`~/.claude/projects/**/*.jsonl`. The parser reads token/timestamp metadata and
does not upload it unless a separately enabled Hive report includes aggregate
metrics.

## Development

```bash
git clone https://github.com/penthoy/probiotic.git
cd probiotic
uv sync --extra dev --extra hive-server
uv run pytest
uv build
```

See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and
[CHANGELOG.md](CHANGELOG.md). Probiotic is available under the Apache License
2.0.
