# James Backbone (Redis + Watcher)

This folder implements the James event backbone and initial agents.

## Implementation docs

- `docs/AI_ACTION_PLAN.md`
- `docs/ARCHITECTURE.md`
- `docs/EVENTS.md`
- `docs/JAMES_REVIEW.md`
- `docs/MAIL_AGENT.md`
- `docs/NODES.md`
- `docs/POLICY.md`
- `docs/VOICE.md`

## Quick Start (Redis)

Redis runs as a native systemd service (`redis-server.service`). Auth and persistence are configured:

```
redis-cli -a "$REDIS_PASSWORD" ping
```

Credentials are in `james/.env` (gitignored).

## Logging

All components use structured JSON logging to stderr (captured by systemd journal).

Output format (one JSON object per line):

```json
{
  "ts": "2026-02-04T20:32:36+0100",
  "level": "info",
  "component": "james.watcher",
  "msg": "started",
  "channel": "james.events.system"
}
```

Set `JAMES_LOG_LEVEL` to `DEBUG`, `INFO`, `WARNING`, or `ERROR` (default: `INFO`).

View logs via journalctl:

```
journalctl --user -u james-watcher -f
journalctl --user -u james-analyst --since "1 hour ago"
journalctl --user -u james-audit --priority=err
```

## Watcher (single node)

1. Install deps:

```
pip install -r requirements.txt
```

2. Run watcher:

```
PYTHONPATH=~/clawd/workspace \
JAMES_NODE=main-host JAMES_ROLE=storage \
REDIS_URL=redis://:yourpass@127.0.0.1:6379/0 \
python3 james/agents/watcher/watcher.py
```

## Pub/Sub test

Terminal A:

```
PYTHONPATH=~/clawd/workspace REDIS_URL=redis://:yourpass@127.0.0.1:6379/0 \
python3 james/tools/subscribe_events.py
```

Terminal B:

```
PYTHONPATH=~/clawd/workspace REDIS_URL=redis://:yourpass@127.0.0.1:6379/0 \
python3 james/tools/publish_event.py --type system.metrics --severity low --payload '{"test":true}'
```

## Audit logger

Subscribes to all channels and writes JSON lines to `james/audit/audit.log`.

```
PYTHONPATH=~/clawd/workspace REDIS_URL=redis://:yourpass@127.0.0.1:6379/0 \
python3 james/tools/audit_logger.py
```

## Analyst (local LLM)

Consumes `james.events.*` and publishes decisions to `james.decisions`.

```
PYTHONPATH=~/clawd/workspace \
JAMES_NODE=main-host \
REDIS_URL=redis://:yourpass@127.0.0.1:6379/0 \
OLLAMA_MODEL=qwen2.5-coder \
python3 james/agents/analyst/analyst.py
```

## Policy engine

Consumes `james.decisions` and emits `james.actions` with approval/deny/allow outcomes.

```
PYTHONPATH=~/clawd/workspace \
JAMES_NODE=main-host \
REDIS_URL=redis://:yourpass@127.0.0.1:6379/0 \
python3 james/agents/policy/policy_engine.py
```

## Mail Agent (dry-run)

Reads mail fixtures and emits `mail.*` events to `james.events.mail`.

```
PYTHONPATH=~/clawd/workspace \
JAMES_MAIL_DRY_RUN=1 JAMES_MAIL_STDOUT=1 \
python3 james/agents/mail/mail_agent.py --dry-run
```

## Voice Stub

Consumes actions/decisions and emits `voice.*` events to `james.events.voice`.

```
PYTHONPATH=~/clawd/workspace \
python3 james/agents/voice/voice_stub.py --stdout
```

## Systemd (optional)

- `systemd/james-redis.service` runs the docker compose stack (not needed if using native redis).
- `agents/watcher/systemd/james-watcher.service` runs the watcher.
- `agents/analyst/systemd/james-analyst.service` runs the analyst.
- `agents/policy/systemd/james-policy.service` runs the policy engine.
- `agents/mail/systemd/james-mail.service` runs the mail agent.
- `agents/voice/systemd/james-voice.service` runs the voice stub.
- `tools/systemd/james-audit.service` runs the audit logger.

Install a unit:

```
cp agents/watcher/systemd/james-watcher.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now james-watcher
```

All services log structured JSON to the systemd journal.