Agentic Finance Platform (Constrained)

A constrained planner–executor API for regulated financial and enterprise workflows. The LLM only proposes a plan (tool calls); validation and execution are deterministic and auditable. Tools are defined and run via an external MCP server. The design fits regulated finance and enterprise workflows: you get a clear audit trail (what was planned and what was run), no black-box execution by the model, and a single place to plug in governance (approvals, limits) before any tool runs.

Docs

• Flow diagram — End-to-end request path and tool discovery/execution.
• Architecture — Components, design principles, and why this fits regulated finance.

Quick start

# Install (uv)
uv sync

# Configure (copy and edit)
cp .env.example .env
# Set OLLAMA_MODEL to a model you have (e.g. ollama pull qwen2.5:14b)
# Optionally: DATABASE_URL, TRADING_MCP_URL, TRADING_MCP_SESSION_ID

# Run
uv run agentic-serve

API: http://localhost:8081

• POST /plan — Send user_id, message (and optional roles, allowed_books, allowed_tools). Returns plan + execution (each plan step run via MCP).
• GET /health — Liveness.
• GET /health/audit, /health/context, /health/tools — Config and tool-registry status.

How it works

1. Request → Context is built (user, message, request_id).
2. Plan → Ollama is given the tool list (from MCP or static fallback) and returns tool calls only.
3. Validate → Tool calls become a structured Plan (steps with tool_name + parameters).
4. Audit → Plan is written to the DB if DATABASE_URL is set.
5. Execute → Each step is run via MCP tools/call. Results are returned with the plan.

The LLM never executes; the executor calls your MCP server for each step. Governance (approvals, limits) can sit between plan and execution later.

Environment

Variable	Purpose
OLLAMA_BASE_URL, OLLAMA_MODEL	Planner LLM (required).
DATABASE_URL	Plan audit + optional conversation persistence.
TRADING_MCP_URL	MCP server for tools/list and tools/call.
TRADING_MCP_SESSION_ID	Session header for MCP (if required by your server).

Todos

• Governance integration — Wire a governance layer (approvals, risk limits, RBAC) between plan validation and execution; integrate with trading or control-plane repo so only approved plans are executed.
• Multi-turn context — Re-enable conversation history (load/append turns per user) so the planner receives prior messages and assistant summaries for follow-up requests.

License

See repository.