# Migration guide: Hivemind 1.x → 2.0

This guide covers breaking changes and new configuration for Hivemind 2.0.

## Breaking changes

### 1. Provider config schema

- **Unchanged:** Existing model strings like `github:gpt-4o`, `openai:gpt-4o`, and `auto` work as before.
- **New backends** require new config sections. Add to `hivemind.toml` as needed:

```toml
[providers.ollama]
enabled = true
base_url = "http://localhost:11434"

[providers.vllm]
enabled = false
base_url = "http://vllm-host:8000"
api_key = ""

[providers.custom]
enabled = false
base_url = "http://my-endpoint:8080"
api_key = ""
model_prefix_strip = "custom-"

[providers.fallback_order]
order = ["anthropic", "openai", "ollama"]
```

- The v2 LLM router is used when at least one backend can be registered (e.g. API keys set). Otherwise the legacy `ProviderRouter` is used.

### 2. Agent sandboxing

- **Default:** Agent execution goes through `AgentSandbox` when `[sandbox]` is present and `enabled = true`.
- **Disable:** Set `sandbox.enabled = false` to run agents without sandbox (1.x behavior).
- **Per-role overrides:** Use `[[sandbox.roles]]` to set `max_tool_calls`, `allowed_tool_categories`, or `filesystem_write` per role.

```toml
[sandbox]
enabled = true
default_max_tool_calls = 20

[[sandbox.roles]]
role = "research"
max_tool_calls = 40
allowed_tool_categories = ["research", "knowledge"]

[[sandbox.roles]]
role = "code"
filesystem_write = true
```

### 3. PII redaction in memory

- **Default:** If `[compliance]` has `pii_redaction = true`, content is redacted before being stored in the memory store.
- **Disable:** Set `compliance.pii_redaction = false` to store raw content (1.x behavior).
- **GDPR:** Set `compliance.gdpr_mode = true` to also redact NAME and ADDRESS (requires optional `spacy` for NER).

```toml
[compliance]
pii_redaction = true
pii_types = ["EMAIL", "PHONE", "SSN", "CREDIT_CARD", "API_KEY"]
gdpr_mode = false
audit_logging = true
data_residency = "us"
```

## New features (optional)

- **Audit log:** When `compliance.audit_logging = true`, each run writes an append-only audit file under `{data_dir}/audit/{run_id}.audit.jsonl`. Use `hivemind audit <run_id>` and `hivemind audit verify <run_id>`.
- **Explainability:** Use `hivemind explain <run_id>` and `hivemind simulate "<task>"` for decision records and dry-run planning.
- **Provider fallback:** Configure `providers.fallback_order` so failed requests are retried on the next backend; `PROVIDER_FALLBACK` events are emitted.

## Optional dependencies

- **Ollama / explainability:** No extra deps (use built-in httpx).
- **Compliance (NER-based PII):** `pip install 'hivemind-ai[compliance]'` or `pip install spacy>=3.7` and `python -m spacy download en_core_web_sm`.

## Summary

| Area        | 1.x behavior              | 2.0 default                         | To keep 1.x behavior              |
|------------|----------------------------|-------------------------------------|------------------------------------|
| Providers  | Single router, env-based   | v2 router when keys set              | No change for existing model names |
| Execution  | Direct agent run           | Sandbox (quotas, tool limits)        | `sandbox.enabled = false`         |
| Memory     | Store raw content          | PII redaction when compliance on     | `compliance.pii_redaction = false` |
| Audit      | None                       | JSONL audit when audit_logging on    | `compliance.audit_logging = false` |
