feat(data-analytics-demo): T-08 narrative — local Ollama LLM pipeline#88
Merged
Merged
Conversation
Phase 4 of the data-analytics-demo bolt-on. Reads the SHAP summary that the ML layer (#87) writes, sends a templated prompt to a local Ollama daemon, and saves an executive-facing markdown narrative — never touching a cloud LLM API. What lands: - narrative/ollama_client.py — env-var-gated host/model resolution (defaults: localhost:11434 + llama3.1:8b-instruct-q4_K_M), AC-4.3 assertion that no cloud-LLM credentials are present at invocation, AC-4.2 remediation hint when Ollama is unreachable. - narrative/prompts.py — the executive-brief prompt template; SHAP-summary rendering is the only call point. - narrative/generate.py — orchestration. Reads shap_summary.json, builds the prompt, calls Ollama, wraps the body with provenance metadata (model id, SHAP source path, timestamp, "external calls: 0" assertion-enforced advertisement) — satisfies AC-4.1, AC-4.4, AC-4.5. - tests/test_narrative.py — 7 cases covering AC-4.1〜4.5 plus missing-data and prompt-builder paths. Uses monkeypatch to stub `ollama.Client` so no network is required in CI. - Makefile narrative target + cli.py narrative subcommand wire-up. AC coverage (mock-Ollama tests + real-Ollama smoke locally): - AC-4.1 produces output.md PASS - AC-4.2 unreachable Ollama PASS (clear RuntimeError with "ollama serve" hint) - AC-4.3 external API guard PASS (raises before any client call) - AC-4.4 cites shap_summary.json PASS - AC-4.5 model identifier in output PASS Local verify: - ruff OK / mypy OK (14 source files) / pytest 22 PASS / coverage 87.20% - Real smoke vs Ollama (gemma3:4b, env-var override): 3-paragraph executive narrative produced end-to-end, all metadata fields present. Design note: the literal AC-4.5 default model name is preserved as the package default; deployments running a different quantized variant can override via the OLLAMA_MODEL env var without code changes.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
2 tasks
leagames0221-sys
added a commit
that referenced
this pull request
May 21, 2026
…#88) Phase 4 of the data-analytics-demo bolt-on. Reads the SHAP summary that the ML layer (#87) writes, sends a templated prompt to a local Ollama daemon, and saves an executive-facing markdown narrative — never touching a cloud LLM API. What lands: - narrative/ollama_client.py — env-var-gated host/model resolution (defaults: localhost:11434 + llama3.1:8b-instruct-q4_K_M), AC-4.3 assertion that no cloud-LLM credentials are present at invocation, AC-4.2 remediation hint when Ollama is unreachable. - narrative/prompts.py — the executive-brief prompt template; SHAP-summary rendering is the only call point. - narrative/generate.py — orchestration. Reads shap_summary.json, builds the prompt, calls Ollama, wraps the body with provenance metadata (model id, SHAP source path, timestamp, "external calls: 0" assertion-enforced advertisement) — satisfies AC-4.1, AC-4.4, AC-4.5. - tests/test_narrative.py — 7 cases covering AC-4.1〜4.5 plus missing-data and prompt-builder paths. Uses monkeypatch to stub `ollama.Client` so no network is required in CI. - Makefile narrative target + cli.py narrative subcommand wire-up. AC coverage (mock-Ollama tests + real-Ollama smoke locally): - AC-4.1 produces output.md PASS - AC-4.2 unreachable Ollama PASS (clear RuntimeError with "ollama serve" hint) - AC-4.3 external API guard PASS (raises before any client call) - AC-4.4 cites shap_summary.json PASS - AC-4.5 model identifier in output PASS Local verify: - ruff OK / mypy OK (14 source files) / pytest 22 PASS / coverage 87.20% - Real smoke vs Ollama (gemma3:4b, env-var override): 3-paragraph executive narrative produced end-to-end, all metadata fields present. Design note: the literal AC-4.5 default model name is preserved as the package default; deployments running a different quantized variant can override via the OLLAMA_MODEL env var without code changes. Co-authored-by: leagames0221-sys <leagames0221@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 4 of the data-analytics-demo bolt-on. The package now produces an executive-facing narrative from the churn SHAP summary — entirely on a local Ollama daemon, with a runtime assertion that no cloud-LLM credential is in the environment.
What lands
narrative/ollama_client.pyOLLAMA_HOST/OLLAMA_MODELenv-var resolution; AC-4.3 credential-leak guard; AC-4.2 remediation hint on connection failurenarrative/prompts.pynarrative/generate.pytests/test_narrative.pyMakefile narrative+cli.py narrativeAC coverage
make narrativeproducesoutput.mdtest_ac_4_1_produces_output_markdown+ real Ollama smoketest_ac_4_2_unreachable_ollama_clear_errortest_ac_4_3_external_api_env_blocks_invocation+ unitshap_summary.jsontest_ac_4_4_and_4_5_metadata_blockDefaults & overrides
OLLAMA_HOSTdefaults tohttp://localhost:11434OLLAMA_MODELdefaults tollama3.1:8b-instruct-q4_K_M(literal AC-4.5 value)Local verify
ruff+mypy --strictclean (14 source files)pytest— 22 passed, coverage 87.20%OLLAMA_MODEL=gemma3:4b, the model already pulled locally): end-to-end produces a 3-paragraph executive narrative; all 5 metadata fields present; no external network calls.Test plan