Metadata-Version: 2.4
Name: probiotic
Version: 0.3.8
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
Author: Tao Zhang
License: MIT License
        
        Copyright (c) 2026 Tao Zhang
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,automation,cli,symbiont
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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 MIT license.
