DataBP POC
DataBP POC / Documents / Implementation guide

DIG-656 Implementation Guide: Morgan, a pluggable agent service

Building and deploying the service.

Morgan, the agent (DIG-656). Built from Pilot knowledge 111 item 818, version 5, as kept while building; private details such as addresses, identifiers and paths are masked here.

Implementation Guide (one part)

Branch Delivery Document — Level 4 — Implementation Guide

Effort DIG-656 — Morgan: build — branch rayserrano2735/dig-656-morgan-build
Governed by Standard: Branch Delivery Documents (K#12 I#27)
References Design: Morgan, the POC's agent: design document, knowledge 111 item 817 v8 — profiling: none: the design's references say why — test plan: DIG-656 Test Plan: Morgan, knowledge 111 item 819
Prerequisites Sage's code at rayserrano2735/digest-datavault 47c4608, infra/aws; the vault items "dv-digest Anthropic API key", "DataBP Semantic Layer Credential Token 2" and "Agent Code - Morgan"; the claude-ws AWS key (project setup, item 802)
Companions None: one part. The page lives in Integrationals/databp-demo, built in the same workflow
Status v1 — DRAFT — written 2026-11-20 13:48Z (written inside Ray's workflow approval of 2026-11-20 08:46 ET, answer 1y; not separately agreed)
Audience Claude, who builds; Ray, who decides
Author Ray Serrano; edited by Claude — 2026-11-20
Classification Internal — Data Management
Official copy method Copied from this governed template by AGENTIC.DATASKILLS.KNOWLEDGE_ITEM_FROM_TEMPLATE; template SHA-256 recorded in the created item

1. Purpose and grounding recap

This guide implements Morgan, the POC's agent: design document, knowledge 111 item 817 v8 and does not relitigate its decisions.

Design decision Settled rule used by the implementation
D-1 Sage's conversation loop, streaming, guard, access code, allowance and page are copied, changed only where DataBP differs
D-2 Metric tools call dbt's hosted Semantic Layer GraphQL interface, Production environment [id]
D-3 The catalogue is read at start and kept 15 minutes
D-4, D-5 Morgan's instructions and suggested questions; the page "Ask Morgan"
D-6 Secrets in AWS Parameter Store under /databp/morgan, from the three vault items
D-7, D-8 One function, databp-morgan-conversation, values as Sage's; model claude-sonnet-5-5
D-9 A core apart from a persona and a route, chosen by the settings AGENT_PERSONA and AGENT_ROUTE

Code in this guide is an illustrative pattern: more than pseudocode, less than shipping code. Do not copy it into the repo; implement it against the branch. Development is done when the output is shown correct against real data, per K#12 I#26.

Pattern declaration

2. Scope

Deliverables

  1. agent/core: conversation.py, web.py, asgi.py and plugins.py, from Sage's conversation_function.py, web_functions.py and conversation_asgi.py.
  2. agent/routes/dbt_semantic_layer.py: list-metrics, get-dimensions and query-metrics over GraphQL.
  3. agent/personas/morgan.py: Morgan's instructions and suggested questions.
  4. agent/deploy.py, agent/run.sh and agent/requirements-lambda.txt, from Sage's deployment.
  5. agent/tests: Sage's tests kept, plus the route's and the plugins'.
  6. In databp-demo: ask.html, Morgan's page with her portrait.

Finance workbook delivery

For finance reporting branches, name the repository generation script, shared mart-level report query and parameters, reproducible generation/refresh steps, workbook metadata and sheets, and preservation of consumer observations under K#12 I#27. Otherwise state NA with a reason.

NA: not a finance reporting branch.

What stays the same

The dbt project, its models, metrics and tests; the Hex app; DV Digest and Sage.

Intentionally not done

The site's beautification and the rename to POC (Ray, 08:29 ET); Sage's invitation function and its MCP connector; more environments than one (D-7).

Identity recipes

Entity Natural code Surrogate-key composition Minting location
None None: Morgan mints no keys None None

3. Grounded in code and complete consumer set

Every edit below names a file and object read from the stated branch.

Touched object Exact file Consumers found Verification command and clock
conversation loop Sage infra/aws/conversation_function.py, answer() and the guard conversation_asgi.py, handler() Read at 47c4608, 2026-11-20 13:50 UTC
the MCP session Sage infra/aws/web_functions.py, digest_session() answer() only Same read
the streaming entry Sage infra/aws/conversation_asgi.py, app run.sh through the Lambda web adapter Same read
the deployment Sage infra/aws/deploy_functions.py and deploy_lambda.py none in DataBP Same read

4. Baseline

Baseline ID Behavior or value Capture command or query Captured result and clock Reconciliation condition
B-1 October 2026 unbilled revenue through the hosted Semantic Layer with Token 2 sl_probe.py, createQuery then query 1,410 dollars, 2026-11-20 13:46 UTC Morgan's answer for October equals it

5. Ordered implementation steps

  1. Copy Sage's three core files into agent/core, renaming imports; replace digest_session with plugins.route_session(), and SYSTEM_PROMPT with plugins.persona().SYSTEM_PROMPT; the guard's retry wording names the persona's product, not DV Digest. Keep every limit and constant.
  2. Write agent/routes/dbt_semantic_layer.py: a class whose list_tools() returns the three tools with Sage's input schemas, and whose call_tool() runs GraphQL: metrics for list-metrics and get-dimensions, createQuery then query (polled each 0.5 seconds, 60 seconds at most) for query-metrics, returning rows and labels as Sage's backend does. get-manifest-version returns a clock bucket of 15 minutes, so the core's catalogue cache holds 15 minutes (D-3).
  3. Write agent/personas/morgan.py: the instructions (who Morgan is; the data provider, four documents, five checks, two dollar figures, months; every figure from a query; synthetic data) and four suggested questions (D-5).
  4. Write agent/deploy.py from Sage's deployment: one function databp-morgan-conversation, its role, its log group, its URL with CORS for https://integrationals.github.io and http://localhost:8000, the three secrets into /databp/morgan from their vault references.
  5. Tests: Sage's kept with the route mocked; new ones for the route (GraphQL calls mocked) and the plugins; seen red, then green.
  6. Deploy; ask the two probe questions through the function URL; then the page.

Each step states the exact file, object, pattern citation, design or profiling citation, literal first-pass code, expected movement, and any required target rebuild.

6. Tests

Existing-test dispositions

Test Layer Disposition: keep, rewrite, or delete Reason
Sage's test_web_functions.py, conversation and guard tests 3 Keep, rewritten against agent.core with a fake route The core is Sage's
Sage's invitation and access-request tests 3 Delete The invitation function is not copied

New and changed tests

agent/tests/test_route.py: list_tools names three tools; list-metrics maps GraphQL metrics; get-dimensions refuses an unknown metric with the list of metrics; query-metrics builds createQuery with the metric and group_by, polls to SUCCESSFUL, returns rows; a FAILED query becomes a refusal. agent/tests/test_plugins.py: AGENT_PERSONA=morgan loads Morgan; an unknown persona or route fails at start.

7. Build sequence and verification

Order Literal command Expected result Baseline reconciliation
1 python3 -m unittest discover agent/tests All pass None
2 python3 agent/deploy.py Function URL printed None
3 curl the function URL with the access code and "What did October's disagreements cost?" Reply with 1,410 and 2,070 and two queries B-1

Verification queries

dbt's MCP query_metrics for unbilled_revenue and revenue_at_risk by month, October 2026, equals Morgan's reply.

8. Decisions recorded in this guide

ID Weed-level choice Rationale
G-1 The route mimics an MCP client's list_tools and call_tool Sage's core runs unchanged against any route (D-9)
G-2 The catalogue's 15 minutes come from get-manifest-version returning a 15-minute clock bucket The core's cache stays Sage's code (D-3)

9. Rollback

Delete the function databp-morgan-conversation, its role and log group, and the parameters under /databp/morgan; revert the pull requests.

10. What this guide does not cover

Exclusion Canonical home
The page's design moves The site's beautification phase
More environments Design D-7

Compliance record

Built by the author last, before the document is presented for agreement (Standard: Branch Delivery Documents, K#12 I#27, "Compliance record before agreement"): every section and field of this template shown present and filled, by infra/workstation/pilot/compliance_sections.py; every rule of that standard and of the standards it cites, each with the passage that meets it or marked NOT MET; and the decisions the document carries. While this section reads NOT BUILT, the document is not presented for agreement.

NOT BUILT.