# AgroMatrix Tools Stack (Stepan)

## Quick start

```bash
make up
```

## Demo telemetry ingest

```bash
make seed
```

## CrewAI (Stepan only)

Перед запуском:

```bash
export PYTHONPATH="$PWD/packages/agromatrix-tools"
```


```bash
PYTHONPATH="$PWD/packages/agromatrix-tools" python3 crews/agromatrix_crew/run.py "Покажи останні спостереження по вологості ґрунту"
```

## Spreadsheet demo

```bash
python3 scripts/demo_spreadsheet.py
```

## Notes
- Запис у farmOS відбувається тільки через Integration Service.
- Під-агенти CrewAI не спілкуються з користувачем напряму.

## Security (P0)
- Integration Service accepts writes only with HMAC headers (X-AGX-SIGNATURE, X-AGX-TIMESTAMP, X-AGX-NONCE).
- Configure AGX_HMAC_SECRET in env.
- farmOS write uses service account (FARMOS_USER/FARMOS_PASSWORD).

## DLQ
- Failed writes go to DLQ (Redis stream or /data/dlq.jsonl).
- Replay: `make replay-dlq`.

## Audit limits
- AGX_AUDIT_MAX_BYTES=4096
- AGX_AUDIT_REDACT_KEYS=token,secret,password,authorization,cookie,api_key,signature

## Trace testing
```bash
PYTHONPATH="$PWD/packages/agromatrix-tools" python3 crews/agromatrix_crew/run.py --trace trace-demo-001 "перевір trace"
```

## farmOS UI (опційно, через reverse-proxy)

1) Згенеруй bcrypt-хеш пароля:
```bash
docker run --rm caddy:2 caddy hash-password --plaintext 'your_password'
```

2) Заповни env:
- FARMOS_UI_PORT=18080
- FARMOS_UI_USER=admin
- FARMOS_UI_PASS_HASH=<hash>

3) Запусти профіль:
```bash
docker compose -f infra/compose/docker-compose.yml --profile farmos_ui up -d
```

Перевірка:
```bash
curl -I http://127.0.0.1:18080
# 401
curl -u admin:<pass> http://127.0.0.1:18080
```

Примітка: farmOS не має host-портів і залишається доступним тільки всередині docker network.


## Dictionaries & Normalization
- Source of truth: `data/dictionaries/dictionaries.yaml`
- Pending terms: `data/dictionaries/pending.jsonl`

Demo:
```bash
python3 scripts/demo_dictionary.py
```

Rules:
- If confidence < 0.85 or no match → pending record is written
- Use `tool_dictionary` before planning or writing


## OperationPlan Manager (P0)
- Data: `data/operations/operation_plans.jsonl`
- Schema: `crews/agromatrix_crew/operation_schema.json`

Demo:
```bash
python3 scripts/demo_operation_plan.py
```


## Dictionary Review Workflow (P0.5)
Pending review:
```bash
python3 scripts/dict_review.py list
python3 scripts/dict_review.py approve --ref pending.jsonl:1 --map-to crop_wheat_winter
python3 scripts/dict_review.py apply
```
Auto-approve (safe categories):
```bash
python3 scripts/dict_review.py auto-approve --min-score 0.97 --category unit --dry-run
```


## Telegram-операторські команди (Pending Review)
ENV:
- AGX_OPERATOR_IDS=12345,67890
- AGX_OPERATOR_CHAT_ID=-100123456 (optional)

Команди:
- /pending
- /pending_show pending.jsonl:17
- /approve pending.jsonl:17 map_to crop_wheat_winter
- /reject pending.jsonl:17 "reason"
- /apply_dict
- /pending_stats
- /whoami

### Operator flags
/pending --limit 20
/pending --category unit
/pending --category operation --limit 50
/approve pending.jsonl:17 map_to crop_wheat_winter --apply

Note: --apply requires AGX_ALLOW_APPLY=1 or AGX_OPS_MODE=1