Story-1009: MatterChatAgent v1 prompt and tool wiring

Story 1009 Epic 749🔗 Chain of CustodyAgent Platform11 files · +886/−41

PR #23 · pramaan-io/pramaan-agents · merged 2026-06-03

How it flows

sequenceDiagram
  autonumber
  participant agent as MatterChatAgent v1
  participant harness as Strands harness
  participant db as Agents DB
  agent->>harness: load prompt v1
  agent->>harness: register 7 tool stubs
  harness->>harness: tools=[] replaced
  harness-->>db: sync prompt + schemas

tools/matter_chat_tools.py + db/prompt_registry_sync.py

Method	in → out	what it does
`search_documents`	`(matter_id, query, limit) → dict[str, Any]`	finds documents inside a given matter
`fetch_quote`	`(matter_id, document_id, quote_id) → dict[str, Any]`	pulls the exact citation text for one quote
`get_contradictions`	`(matter_id, contradiction_id) → dict[str, Any]`	surfaces claim-versus-claim conflicts in the matter
`sync_matter_chat_agent_v1`	`(engine, firm_id, model_id, prompt_path) → None`	deploys the v1 prompt and tool schemas into agents tables

What changed, file by file

src/pramaan_agents/tools/matter_chat_tools.py+320

Defines the seven MatterChatAgent v1 tool stubs for search, open, quote, events, claims, contradictions, entities that raise until PR ten-ten lands.

new method	signature
`tool`	`(func) → F`
`_object_schema`	`(properties, required) → JSONSchema`
`_array_of`	`(item_schema) → JSONSchema`
`_not_implemented`	`(tool_name) → NoReturn`
`search_documents`	`(matter_id, query, limit) → dict[str, Any]`
`open_document`	`(matter_id, document_id) → dict[str, Any]`
`fetch_quote`	`(matter_id, document_id, quote_id) → dict[str, Any]`
`get_events`	`(matter_id, limit) → dict[str, Any]`
`get_claims`	`(matter_id, claim_id) → dict[str, Any]`
`get_contradictions`	`(matter_id, contradiction_id) → dict[str, Any]`
`get_entities`	`(matter_id, entity_type) → dict[str, Any]`

New fields: UUID_SCHEMA : JSONSchemaQUOTE_ID_SCHEMA : JSONSchemaTEXT_SCHEMA : JSONSchemaCITATION_SCHEMA : JSONSchema

src/pramaan_agents/db/prompt_registry_sync.py+171

Deploy-time sync writing prompt v1 and tool registry schemas into the agents tables.

new method	signature
`sync_matter_chat_agent_v1`	`(engine, firm_id, model_id, prompt_path) → None`
`_json_dump`	`(value) → str`
`main`	`(argv) → int`

src/pramaan_agents/runtime/matter_chat_prompt.py+39 −38

Runtime loader that reads the v1 prompt file and renders conversation history for the agent.

new method	signature
`load_matter_chat_prompt_v1`	`(prompt_path) → str`
`_render_history`	`(history) → str`
`_render_user_turn`	`(message) → str`

What this PR does NOT do

tool bodies
guardrail logic
schema migration
production runtime
real answers

prompt pinned to v1

tools indexed cleanly

sync is deploy-time only

calling any tool raises NotImplementedError

bodies owned by PR ten-ten

guardrails owned by PR ten-eleven

Files changed (11)

File	±
`docs/walkthroughs/story-1009-walkthrough.html`	+54
`scripts/sync-matter-chat-agent-v1.py`	+13
`src/pramaan_agents/agents/matter_chat_agent/prompt_v1.md` ★	+74
`src/pramaan_agents/db/prompt_registry_sync.py` ★	+171
`src/pramaan_agents/runtime/matter_chat_prompt.py`	+39 −38
`src/pramaan_agents/runtime/strands_harness.py`	+2 −1
`src/pramaan_agents/tools/__init__.py`	+5
`src/pramaan_agents/tools/matter_chat_tools.py` ★	+320
`tests/test_context_builder.py`	+2 −1
`tests/test_matter_chat_agent_wiring.py`	+190
`tests/test_matter_chat_prompt.py`	+16 −1