Counter_Risk

A programmatic replacement for the MOSERS spreadsheet workflow used to evaluate counterparty risk and produce the monthly Counterparty Exposure reporting package (Excel workbooks + PowerPoint).

Who this is for

• Operators (non-technical): run the monthly process via a button-driven Runner (Excel or a simple Windows app) and deliver the output files. Operators do not need repo access.
• Maintainers: develop and maintain the pipeline in this repository, primarily through agent-driven issues and PRs.

What the pipeline produces

• Updated historical Excel workbooks (time series inputs for charts)
• Updated monthly PowerPoint (screenshots replaced + chart links refreshed)
• A run folder with a manifest (inputs, hashes, warnings, summaries). The manifest carries a top-level manifest_schema_version (currently "counter-risk-manifest/v1") so the contract can evolve safely, and a provenance block tying the run to the exact code that produced it: tool, tool_version, git_sha (best-effort; null outside a git checkout), python_version, and platform.
• Registry-backed counterparty and clearing-house name matching (see docs/name_registry.md)
• A DATA_QUALITY_SUMMARY.txt and manifest data_quality object for green/yellow/red operator review (see docs/data_quality.md)
• A concentration_metrics.csv with Top 5/Top 10 share and HHI per (variant, segment) (see docs/concentration_metrics.md)
• Optional risk_rankings.csv and risk_top_movers.csv risk proxy outputs when source columns exist (see docs/risk_proxy_outputs.md)
• A limit_breaches.csv when configured exposure limits are breached (see docs/limit_monitoring.md)
• Optional “distribution” deliverables (static PPT/PDF) that do not prompt for link refresh

Output Generator Configuration

Outputs are registered per run via output_generators in YAML config files. Each entry has:

• name: unique identifier for the generator
• registration: either builtin:<id> or <python_module>:<symbol>
• stage: one of historical, ppt_master, ppt_refresh, ppt_post_distribution
• enabled: true/false

Example:

output_generators:
  - name: historical_workbook
    registration: builtin:historical_workbook
    stage: historical
    enabled: true
  - name: ppt_screenshot
    registration: builtin:ppt_screenshot
    stage: ppt_master
    enabled: true
  - name: ppt_link_refresh
    registration: builtin:ppt_link_refresh
    stage: ppt_refresh
    enabled: false
  - name: custom_exhibit
    registration: my_package.outputs:CustomExhibitGenerator
    stage: ppt_post_distribution
    enabled: true

Setting enabled: false cleanly skips that generator for the run.

Repo Cash Source Configuration

Repo Cash loading supports layered source selection and audit-friendly overrides:

1. cash_overrides_<as_of_date>.csv (or explicit cash_overrides_csv)
2. Structured source (cash_source_type: csv|xlsx with cash_source_path)
3. PDF source (cash_source_type: pdf or daily_holdings_pdf)

Optional config keys:

• cash_source_type: csv, xlsx, pdf, or none
• cash_source_path: explicit source file path
• cash_overrides_csv: explicit overrides CSV path
• required_repo_counterparties: counterparties that must be present in the loaded map
• cash_total_min / cash_total_max: expected total-range checks

Source choice and overrides are emitted in run warnings, which are persisted in manifest.json.

Start here

• Project agent guide: AGENTS.md
• Consumer repo workflow rules: CLAUDE.md
• How to use labels/keepalive/autopilot: WORKFLOW_USER_GUIDE.md
• Issue formatting standard: docs/AGENT_ISSUE_FORMAT.md
• CI/Workflows integration guide: docs/CI_SYSTEM_GUIDE.md
• Keepalive troubleshooting: docs/KEEPALIVE_TROUBLESHOOTING.md
• Consumer setup checklist: docs/SETUP_CHECKLIST.md
• GUI runner usage: docs/gui_runner.md

Name Registry Workflow

Use docs/name_registry.md as the maintainer runbook. The short loop is:

1. Run the mapping diff report before editing the registry.
2. Edit config/name_registry.yml using stable canonical_key values, workbook/report-safe display_name values, and aliases for source spelling variants.
3. Use series_included.by_segment only for intentional segment-level exclusions.
4. Re-run the focused registry tests and confirm the diff report resolves the intended names into NAME_RESOLUTIONS.

Repository automation (high level)

This repo is integrated with the central stranske/Workflows library.

Typical maintainer loop:

1. Write/format an issue using the repo issue format.
2. Label the issue to trigger agent workflows (for example, agents:format then agent:codex).
3. Keepalive iterates on the PR until tasks and acceptance criteria are complete.

If a change requires editing synced workflow files, do it in stranske/Workflows first and then sync.

Testing

Autopilot smoke tests are enabled to validate basic keepalive and automation flow behavior.

Development

Use these maintainer commands from the repository root:

• make lint runs ruff check src/ tests/
• make format runs ruff format src/ tests/
• make test runs pytest -m "not slow"

Manifest Evidence

manifest.json includes an evidence object on each top_exposures entry. The source_id uses the same key namespace as input_hashes (for example, mosers_all_programs_xlsx), and the sheet and row fields point to the workbook location used to produce the exposure fact. Evidence remains local to the manifest and is not exported in LangSmith fleet records.

Slow Test Strategy

Some tests are too expensive for PR feedback, so they are tagged with the slow pytest marker and excluded from PR Gate. They still run in Main CI after merges to main.

Where it runs	Marker filter	Typical duration
PR Gate (pr-00-gate.yml)	not release and not slow	~4 min
Main CI (ci.yml)	(all tests)	~12-15 min
Release E2E (release-e2e.yml)	release	nightly / on label

What counts as "slow":

• tests/pipeline/test_run_pipeline.py — every test_run_pipeline_* test calls run_pipeline() with real Excel fixtures (100-170 s each on CI). Auto-marked via tests/pipeline/conftest.py.
• tests/spec/test_macro_spec_fixtures.py — session-scoped fixture parses three large NISA workbooks (~85 s one-time cost). Module-level pytestmark = pytest.mark.slow.

When adding new tests that parse real workbooks or run full pipeline orchestration, mark them @pytest.mark.slow (or add them to the conftest hook) so the Gate stays fast.

Chat Provider Configuration

The run-context chat assistant now uses LangChain-backed providers (instead of stubs) for openai and anthropic.

• Ensure runtime dependencies are installed before using chat providers (for example pip install -r requirements.txt or pip install -e .).
• Copy .env.example to a local .env (or set variables in your runtime environment).
• Configure at least one credential path:
  • GITHUB_TOKEN (used for OpenAI-compatible GitHub Models path)
  • OPENAI_API_KEY (direct OpenAI path)
  • CLAUDE_API_STRANSKE (Anthropic path)
• Missing package failures are surfaced with explicit install guidance (langchain-openai or langchain-anthropic) before provider calls execute.
• The deterministic local stub provider is disabled by default and only available when COUNTER_RISK_CHAT_OFFLINE_MODE=1 (intended for offline tests/dev only).
• Optional routing/model overrides are also documented in .env.example (LANGCHAIN_PROVIDER, LANGCHAIN_MODEL, slot overrides, timeout/retry settings).
• Chat logging mode defaults to transcript; override with COUNTER_RISK_CHAT_LOG_MODE (transcript, full, off).
• See docs/chat_logging.md for mode behavior, payload fields, and LangSmith trace linkage.
• See docs/langsmith_fleet.md for the dashboard-safe langsmith-fleet.ndjson artifact emitted by monthly risk runs.

Workflow Run Command

The production workflow run path is:

counter-risk run --config <workflow.yml> --as-of-date YYYY-MM-DD --output-dir <runs/<timestamp>>

Examples:

• python -m counter_risk.cli run --config config/all_programs.yml --as-of-date 2025-12-31 --output-dir runs/2025-12-31_000000
• python -m counter_risk.cli run --discover --config config/all_programs.yml --as-of-date 2025-12-31 --output-dir runs/2025-12-31_000000

Optional runtime overrides:

• --strict-policy warn|strict (reconciliation fail policy override)
• --export-pdf / --no-export-pdf
• --formatting-profile <name> (applies supported numeric formatting policies to output writers)
• --settings <path/to/runner-settings.json> (Runner.xlsm / GUI serialized settings payload)

Formatting Profiles

Supported formatting profile values:

• default - preserve template/default number formats.
• currency - USD-style currency formatting for historical notional outputs.
• accounting - accounting-style currency formatting for historical notional outputs.
• plain - non-currency numeric format with two decimals.

Current profile application scope:

• Historical workbook append rows written by the pipeline.
• CPRS-CH/CPRS-FCM static table PNG renderers when invoked with formatting_profile.

Legacy packaging path is still available for release validation only:

• counter-risk run --fixture-replay --config config/fixture_replay.yml --output-dir <path>

GUI Command

For macro-restricted environments, operators can launch the Tkinter runner:

• counter-risk gui
• counter-risk gui --headless --as-of-date 2025-12-31 --mode all (CI/smoke)

Features

• 🐍 Python 3.11+ - Modern Python with type hints
• 🔧 Ruff - Fast Python linting and formatting
• 🔍 MyPy - Strict type checking
• 🧪 Pytest - Testing with 80% coverage requirement
• 🤖 CLI Codex Automation - Gate-triggered keepalive for automated development
• 🔄 Dual Checkout Pattern - Consumer repo + centralized Workflows scripts

Workflows

This repository uses reusable workflows from stranske/Workflows:

Core CI & Quality

Workflow	Purpose	Trigger
Gate	PR validation (CI, lint, tests)	Pull request
CI	Push-to-main continuous integration	Push to main
Autofix	Automatic lint/format fixes	Label: autofix

Agent Workflows (CLI Codex)

Workflow	Purpose	Trigger
Keepalive Loop	Runs Codex CLI after Gate passes	Gate completion, PR label
PR Meta	Updates PR status summaries	PR events
Issue Intake	Creates PRs from labeled issues	Issue labeled
Guard	Security checks for agent execution	Before agent runs
Bot Comment Handler	Processes @codex commands	Issue comments
Autofix Loop	Autofix integration with keepalive	Autofix + agent label

Note: agents-orchestrator.yml is legacy and can be removed. The current architecture uses agents-keepalive-loop.yml which integrates with the Gate workflow for event-driven triggering.

Agent Automation

This template uses the Gate-triggered keepalive architecture:

How It Works

1. Create Issue with structured Scope/Tasks/Acceptance sections
2. Label Issue with agent:codex
3. Issue Intake creates PR from issue
4. Gate Workflow runs CI validation
5. Keepalive Loop triggers after Gate completion
   • Evaluates eligibility (unchecked tasks, no pause labels)
   • Runs CLI Codex via reusable-codex-run.yml
   • Codex implements changes and pushes commits
6. Gate Runs Again → loop continues
7. Completion when all acceptance criteria checked

Key Components

• Activation: PR must have agent:codex label, Gate success, unchecked tasks
• Task Tracking: Agent updates checkboxes in PR body after completing work
• Progress Detection: Automatic checkbox reconciliation via session analysis
• Failure Handling: After 3 failures, adds needs-human label and pauses
• Concurrency: One keepalive run per PR (configurable via agents:max-parallel:N)

Control Labels

Label	Effect
agent:codex	Enables Codex automation
agents:pause	Halts all agent activity
needs-human	Auto-added after failures, blocks keepalive
agents:max-parallel:N	Override concurrent run limit (default: 1)

Using Issues.txt

Add issues to Issues.txt using the structured format, then trigger the intake workflow:

1) Issue title here
Labels: agent:codex, enhancement

## Scope
Explanation of what needs to be done and why.

## Tasks
- [ ] Task 1
- [ ] Task 2
- [ ] Task 3

## Acceptance Criteria
- [ ] All tests pass
- [ ] Code is documented
- [ ] Coverage ≥80%

Implementation notes
- Technical details or constraints

Troubleshooting

Keepalive Not Triggering

• Verify PR has agent:codex label
• Check Gate workflow passed
• Ensure PR body has unchecked tasks
• Look for agents:pause or needs-human labels
• Review keepalive summary comment for skip reasons

No Automated Status Summary

• Verify issue has Scope/Tasks/Acceptance sections
• Run agents-pr-meta.yml manually
• Check PR links to source issue

Agent Failures

After 3 failures, keepalive pauses and adds needs-human:

1. Review failure reason in keepalive summary
2. Fix the issue (code, prompt, auth)
3. Remove needs-human label to resume

Permission Errors

• Verify CODEX_AUTH_JSON or GitHub App credentials are set
• Check environment agent-standard exists
• Ensure PATs have required scopes: repo, workflow

Documentation

• Workflows Repo - Central workflow library
• Consumer README - Complete setup guide
• Keepalive Architecture - Detailed design
• Setup Checklist - Step-by-step configuration

License

MIT License - see LICENSE for details.