# Finance Agent

The maintained finance showcase is [`examples/pydantic/finance_agent.py`](https://github.com/vcoderun/acpkit/blob/main/examples/pydantic/finance_agent.py).

It is the main example for:

- a direct module-level `Agent(...)`, `AdapterConfig(...)`, and configured
  `acp_agent` surface
- `PrepareToolsBridge` mode shaping
- structured native plan generation
- approval-gated writes with `FileSystemProjectionMap`
- file-backed ACP session persistence

## Why This Example Exists

Older examples in this repo split these ideas across separate files. That made the codebase noisy
and kept coverage low in files that were too small to justify keeping around.

`finance_agent.py` intentionally keeps those ACP surfaces together in one realistic workflow:

- `ask` mode for read-only inspection
- `plan` mode for ACP-native structured plans
- `trade` mode for approval-gated note updates

## Run It

```bash
uv run python -m examples.pydantic.finance_agent
```

By default the example uses `TestModel`. Set `ACP_FINANCE_MODEL` when you want a live model.

Remote ACP hosting path:

```bash
acpkit serve examples.pydantic.finance_agent:acp_agent --host 0.0.0.0 --port 8080
acpkit run --addr ws://127.0.0.1:8080/acp/ws
```

## Key Patterns

- the module exports `agent`, `config`, `acp_agent`, and `main`; use
  `acp_agent` when CLI or remote hosting must preserve the custom configuration
- `FinancePlanPersistenceProvider` writes ACP plans into
  `agent_demos/finance-agent/plans/`
- `PrepareToolsBridge` keeps `ask`, `plan`, and `trade` behaviors explicit instead of scattering them across separate examples
- `FileSystemProjectionMap` turns note reads and writes into rich ACP diffs
- `NativeApprovalBridge` keeps mutating writes truthfully approval-gated
