Metadata-Version: 2.4
Name: soma-ai
Version: 0.3.1
Summary: Behavioral monitoring and directive control for AI agents
Project-URL: Homepage, https://github.com/tr00x/soma-core
Project-URL: Repository, https://github.com/tr00x/soma-core
Author-email: Tim Hunt <tr00x@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,behavioral,monitoring,observability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: rich>=13.0
Requires-Dist: tomli-w>=1.0
Provides-Extra: all
Requires-Dist: soma-core[dashboard,dev,otel]; extra == 'all'
Provides-Extra: dashboard
Requires-Dist: textual>=3.0; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
Description-Content-Type: text/markdown

# SOMA

The nervous system for AI agents. Monitors behavior, predicts problems, and intervenes before things go wrong.

```
pip install soma-ai
soma setup-claude
```

That's it. Your Claude Code now has a nervous system.

## Quick start

```bash
# Install
pip install soma-ai

# Connect to Claude Code (installs hooks + status line)
soma setup-claude

# Check it's working
soma status
```

After setup, SOMA runs automatically. Every tool call is monitored. You'll see a status line at the bottom of Claude Code:

```
SOMA + healthy  2% · #42 · quality A
```

## Slash commands

Use these inside Claude Code:

| Command | What it does |
|---------|-------------|
| `/soma:status` | Live status — pressure, quality, vitals, budget, tips |
| `/soma:config` | Settings — modes, thresholds, budget, toggles |
| `/soma:config mode strict` | Strict mode — low thresholds, verbose |
| `/soma:config mode relaxed` | Relaxed (default) — balanced monitoring |
| `/soma:config mode autonomous` | Minimal monitoring for trusted runs |
| `/soma:control quarantine` | Force agent to quarantine (blocks tools) |
| `/soma:control release` | Release from quarantine |
| `/soma:control reset` | Reset behavioral baseline |
| `/soma:help` | Full command reference |

## Terminal commands

```
soma                  # live TUI dashboard
soma status           # quick text summary
soma mode             # show/switch operating mode
soma agents           # list monitored agents
soma setup-claude     # install hooks into Claude Code
soma config show      # print soma.toml
soma export           # export session to JSON
```

## Operating modes

Switch with `soma mode <name>` or `/soma:config mode <name>`:

| Mode | Autonomy | Quarantine at | Verbosity |
|------|----------|---------------|-----------|
| **strict** | human-in-the-loop | 60% | verbose |
| **relaxed** (default) | human-on-the-loop | 80% | normal |
| **autonomous** | fully autonomous | 95% | minimal |

## What it monitors

**5 behavioral signals** per action:
- **Uncertainty** — retries, output chaos, tool diversity
- **Drift** — deviation from established patterns
- **Error rate** — syntax errors, failed commands
- **Cost** — token/dollar burn rate
- **Quality** — A-F grade (syntax, lint, bash success)

**Predicts** problems ~5 actions before they happen.

**Restricts** progressively as pressure rises:

```
HEALTHY (0-24%)  →  CAUTION (25%)  →  DEGRADE (50%)  →  QUARANTINE (75%)  →  RESTART (90%)
   all allowed       warn on writes     bash blocked      read-only           full stop
```

**Explains** in plain English:
- "stuck in Edit→Bash loop on config.py (4 cycles)"
- "3 consecutive Bash failures (error_rate=40%)"
- "scope expanded to tests/, config/"

## How it works

```
Tool call → PreToolUse (can block) → Tool executes → PostToolUse (record + validate)
                                                           │
                                                 Compute vitals → Pressure → Level
                                                           │
                             UserPromptSubmit ← Prediction + RCA + Quality + Tips
```

4 hooks, all configurable:
- **PreToolUse** — blocks dangerous actions under pressure
- **PostToolUse** — records action, validates code, computes vitals
- **UserPromptSubmit** — injects actionable feedback into agent context
- **Stop** — saves state, updates fingerprint, shows session summary

Everything is deterministic. No LLM calls. No network requests. Pure math.

## Configuration

`soma.toml` controls everything:

```toml
[hooks]
verbosity = "normal"      # minimal, normal, verbose
validate_python = true    # syntax check after Write
lint_python = true        # ruff check after Write
predict = true            # anomaly prediction
quality = true            # A-F quality grading

[thresholds]
caution = 0.40
degrade = 0.60
quarantine = 0.80

[weights]
uncertainty = 1.2
drift = 1.5
error_rate = 2.5
```

## Claude Code plugin

SOMA is also available as a Claude Code plugin:

```
/install tr00x/soma-core
```

This auto-registers hooks and adds `/soma:*` slash commands.

## Requirements

- Python >= 3.11
- Claude Code (for hook integration)
- Optional: `ruff` for lint validation, `node` for JS validation

## License

MIT
