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
- Patterns instantiated: Sage's conversation function and its streaming entry point (DV Digest design D-10 to D-13)
- Patterns introduced: The pluggable agent: a route is any object with list_tools and call_tool returning results shaped as an MCP client's, so the core is unchanged when the route changes (D-9)
2. Scope
Deliverables
- agent/core: conversation.py, web.py, asgi.py and plugins.py, from Sage's conversation_function.py, web_functions.py and conversation_asgi.py.
- agent/routes/dbt_semantic_layer.py: list-metrics, get-dimensions and query-metrics over GraphQL.
- agent/personas/morgan.py: Morgan's instructions and suggested questions.
- agent/deploy.py, agent/run.sh and agent/requirements-lambda.txt, from Sage's deployment.
- agent/tests: Sage's tests kept, plus the route's and the plugins'.
- 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
- 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.
- 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).
- 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).
- 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.
- Tests: Sage's kept with the route mocked; new ones for the route (GraphQL calls mocked) and the plugins; seen red, then green.
- 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.