Institutional Securities Lending, Financing, Repo & Prime Brokerage Decision-Support Engine

SecFi Prime Platform is an end-to-end decision-support and optimization engine for a global securities lending, financing, repo, and prime brokerage desk. Built to institutional standards, it combines ten integrated analytical engines — covering counterparty exposure, capital and RWA approximation, book optimization, pricing intelligence, recall and buy-in risk, corporate action impact, custodian reconciliation, collateral optimization, inventory management, and growth analysis — into a single, auditable, human-in-the-loop platform. Built for the desk head and their full team — traders, risk managers, funding strategists, operations, and senior management — with a governance framework, model risk documentation, and operational runbook suitable for a top-tier prime brokerage environment.

This platform is built for the head of a global securities lending and financing desk inside a prime brokerage business at a top-tier bank — and every member of their team:

Ten integrated analytical engines, wired through a single orchestration layer:

Plus the control layer:

• Intraday limit monitoring with what-if simulation (risk/limit_monitor.py)
• Standalone scenario & reverse-stress engine (risk/scenario_engine.py)
• Pricing, limit, and data-quality exception management with approval workflow (risk/exception_manager.py)
• Cross-source data quality controls & anomaly detection (common/data_quality.py)
• Intelligent alert prioritization, deduplication & routing (alerting/prioritizer.py)
• Realized P&L backtesting framework (reporting/backtester.py)

The platform does not trade, book, or execute anything. Every recommendation requires explicit human approval via the desk-facing API before it is acted on. See Governance.

External sources  ──►  Ingestion  ──►  Normalization  ──►  Analytics engines
                                                               │
                                                    ┌──────────┼──────────┐
                                                    │          │          │
                                                  Risk      Price     Optimize
                                                  layer    layer      layer
                                                    │          │          │
                                                    └──────────┼──────────┘
                                                               │
                                                         Orchestration
                                                               │
                                              ┌────────────────┼────────────────┐
                                              │                │                │
                                          Alerting         Reporting          API
                                              │                │                │
                                           Alerts       Daily summary     Desk UI
                                              │           + queues         /v1/...
                                              │
                                          SQL persistence
                                       (secfi.* schema, PostgreSQL)

Full architecture diagram and layer-by-layer description: docs/architecture.md

secfi-prime-platform/
├── src/secfi_platform/
│   ├── common/
│   │   ├── config.py              # YAML config loader with env-var secret resolution
│   │   ├── data_quality.py        # Cross-source DQ profiling, anomaly detection
│   │   ├── enums.py               # Controlled vocabularies (Direction, ProductType, etc.)
│   │   ├── logging_setup.py       # Structured JSON logging with correlation IDs
│   │   └── types.py               # Canonical dataclasses (Position, Counterparty, etc.)
│   ├── ingestion/
│   │   ├── base.py                # SourceConnector ABC + DataSourceUnavailableError
│   │   └── connectors.py          # One connector per source (file-backed for dev)
│   ├── normalization/
│   │   └── schema_mapping.py      # raw dict → canonical objects, with per-field validation
│   ├── risk/
│   │   ├── capital_rwa.py         # EAD / RWA / leverage / RoC approximation
│   │   ├── collateral_optimizer.py# CTD scoring, eligibility, substitution recommendations
│   │   ├── counterparty_risk.py   # Gross/net exposure, stress scenarios, WWR, HHI
│   │   ├── exception_manager.py   # Pricing/limit/DQ exception lifecycle
│   │   ├── inventory_manager.py   # Lendable pool, locate resolution, rehypothecation
│   │   ├── limit_monitor.py       # Intraday utilization dashboard, what-if simulation
│   │   ├── rates_fx.py            # DV01, FX exposure, funding gap, hedge recommendations
│   │   └── scenario_engine.py     # Named event scenarios, comparison matrix, reverse stress
│   ├── optimization/
│   │   └── book_optimizer.py      # Constrained LP: reprice + reroute, capital-aware objective
│   ├── pricing/
│   │   └── pricing_intelligence.py# Specialness classification, dispersion z-score, REPRICE queue
│   ├── recall_buyin/
│   │   └── recall_risk_engine.py  # Buy-in risk score, urgency score, substitute resolution
│   ├── reconciliation/
│   │   └── recon_engine.py        # Pandas-based book↔custodian matching, break classification
│   ├── corporate_actions/
│   │   └── ca_impact_engine.py    # 60-day forward scan, event-type weights, proximity scaling
│   ├── growth/
│   │   └── counterparty_growth.py # GROW/HOLD/REDUCE/REPRICE decision tree
│   ├── explainability/
│   │   └── explain.py             # Shared confidence/priority scoring used by every engine
│   ├── alerting/
│   │   ├── alert_engine.py        # Threshold → Alert objects from each engine's output
│   │   └── prioritizer.py         # Deduplication, throttle, mass-collapse, rank, route
│   ├── reporting/
│   │   ├── backtester.py          # Predicted vs realized P&L calibration framework
│   │   └── daily_summary.py       # Assemble all engine outputs into executive summary + MD
│   ├── orchestration/
│   │   └── scheduler.py           # run_full_cycle() — the DAG scheduler's task body
│   └── api/
│       ├── main.py                # FastAPI app entry point
│       ├── schemas.py             # Pydantic DTOs (boundary only, not internal model)
│       ├── state.py               # Latest cycle output store (in-memory ref build)
│       └── routers/
│           ├── desk.py            # Core desk endpoints (exposure, recs, queues, approvals)
│           └── risk_extended.py   # Limits, scenarios, DQ, capital, rates/FX, alerts
├── sql/
│   ├── schemas/                   # 01-08: reference data, counterparty, book, pricing, recon, CA, capital, audit
│   ├── views/                     # v_book_summary, v_counterparty_exposure_rollup
│   └── procedures/                # sp_age_open_items (nightly aging)
├── tests/
│   ├── fixtures/                  # 8 realistic CSV fixtures (securities, positions, rates, fails, CA, FX...)
│   ├── _helpers.py                # Shared fixture loading → canonical objects
│   ├── unit/                      # 11 unit test modules (121 tests)
│   └── integration/               # 1 full-cycle integration test module (14 tests)
├── scripts/
│   ├── run_daily_batch.py         # EOD full cycle entry point
│   └── run_intraday_cycle.py      # Intraday fast cycle (no recon)
├── examples/
│   └── example_daily_run.py       # Ad-hoc engine usage (notebook-style)
├── configs/
│   ├── base.yaml                  # Environment-agnostic defaults
│   ├── dev.yaml                   # Dev overrides
│   ├── prod.yaml                  # Prod overrides (secrets as ${ENV_VAR_NAME} refs)
│   └── risk_limits.yaml           # Haircuts, stress scenarios, counterparty tier limits
├── infra/
│   └── docker/
│       ├── Dockerfile             # Multi-stage prod image (non-root runtime)
│       └── docker-compose.yml     # Local dev stack: API + PostgreSQL
├── docs/
│   ├── architecture.md            # Full system architecture + technology choices
│   ├── algorithms.md              # Mathematical formulations for every engine
│   ├── data_model.md              # Data schema, required inputs, fallback policy
│   ├── module_specs.md            # Module-by-module API contract reference
│   ├── risk_framework.md          # Risk governance, what this platform IS and IS NOT
│   ├── reporting_design.md        # Output/dashboard specifications
│   ├── governance.md              # Approval workflow, permissions, escalation
│   ├── model_risk.md              # Model inventory, change governance checklist, backtesting plan
│   ├── runbook.md                 # Scheduling, monitoring, incident response
│   ├── testing_validation.md      # Full test pyramid, coverage, known gaps
│   ├── implementation_plan.md     # 4-phase rollout plan, deployment topology
│   ├── assumptions_and_limitations.md  # Every assumption with a stable reference code
│   └── sample_outputs/
│       └── daily_executive_summary_2026-06-18.md  # Real output from a full cycle run
├── .github/workflows/ci.yml       # lint → unit → integration → container build → model-risk gate
├── .env.example                   # Required environment variable documentation
├── .gitignore
├── pyproject.toml                 # Dependencies, tool config
└── README.md                      # This file

Total: 135 tests, 0 failures, across 55+ Python modules.

All connectors implement SourceConnector (ingestion/base.py). The reference build uses local CSV fixtures (tests/fixtures/). Production: swap each connector class's fetch() implementation to call the real vendor API or internal message bus — no analytics code changes.

# configs/base.yaml — key configurable thresholds
pricing:
  specialness_thresholds:
    gc_fee_ceiling_bps: 25         # <25bps = GC
    special_fee_floor_bps: 100     # ≥100bps = Special
    htb_fee_floor_bps: 300         # ≥300bps + high util = HTB
    deep_special_fee_floor_bps: 1000
  min_actionable_gap_bps: 5        # suppress noise repricings below this

capital:
  target_cet1_ratio: 0.115          # 11.5% CET1 target
  cost_of_capital_pct: 0.12         # 12% hurdle rate

alerting:
  thresholds:
    limit_utilization_warn_pct: 0.85    # AMBER threshold
    limit_utilization_breach_pct: 1.00  # BREACH threshold
    buyin_risk_alert_score: 70           # 0-100 scale

All thresholds are desk-configurable without code changes — modify configs/base.yaml (or configs/prod.yaml for environment-specific overrides) and restart the service. Config changes are version-controlled and auditable.

Secrets are never in YAML — only ${ENV_VAR_NAME} references resolved at runtime. See .env.example.

• Python 3.11+
• Docker & Docker Compose (for local stack)
• PostgreSQL 14+ (for full persistent deployment)

# 1. Clone and set up
git clone <internal-repo-url> secfi-prime-platform
cd secfi-prime-platform

# 2. Install dependencies
pip install -e ".[dev]"

# 3. Copy and configure environment
cp .env.example .env
# Edit .env: set SECFI_DB_* values for local Postgres if needed

# 4. Run the full test suite
PYTHONPATH=src:. python3 -m unittest discover -s tests -p "test_*.py"
# Expected: Ran 135 tests in ~0.5s, OK

# 5. Run a cycle against the bundled reference dataset
python3 scripts/run_daily_batch.py --as-of 2026-06-18 --environment dev
# Output: structured JSON logs + daily_executive_summary_2026-06-18.md in outputs/

# 6. Start the API service
uvicorn secfi_platform.api.main:app --reload --port 8000
# Health check: curl http://localhost:8000/healthz

# 7. Optional: local stack with Postgres (applies SQL schemas automatically)
docker compose -f infra/docker/docker-compose.yml up

# Apply all schemas in order (docker-compose does this automatically on first run)
psql -h localhost -U secfi_dev -d secfi_platform_dev \
    -f sql/schemas/01_reference_data.sql \
    -f sql/schemas/02_counterparty.sql \
    -f sql/schemas/03_positions_book.sql \
    -f sql/schemas/04_pricing_market_data.sql \
    -f sql/schemas/05_recon.sql \
    -f sql/schemas/06_corporate_actions.sql \
    -f sql/schemas/07_capital_rwa.sql \
    -f sql/schemas/08_audit_log.sql

# Apply views and procedures
psql -h localhost -U secfi_dev -d secfi_platform_dev \
    -f sql/views/v_book_summary.sql \
    -f sql/views/v_counterparty_exposure_rollup.sql \
    -f sql/procedures/sp_age_open_items.sql

python3 scripts/run_daily_batch.py \
    --as-of $(date +%Y-%m-%d) \
    --environment prod \
    --output-dir /data/secfi/outputs

python3 scripts/run_intraday_cycle.py --as-of $(date +%Y-%m-%d)

# Development
uvicorn secfi_platform.api.main:app --reload --port 8000

# Production (via Docker)
docker build -f infra/docker/Dockerfile -t secfi-prime-platform:$(git rev-parse --short HEAD) .
docker run -p 8000:8000 --env-file .env secfi-prime-platform:<tag>

python3 examples/example_daily_run.py

Base URL: http://<host>:8000/v1
Auto-generated OpenAPI docs: http://<host>:8000/docs

All POST endpoints require a decided_by field and write an immutable audit record to secfi.recommendation_approval_log. Nothing auto-executes.

Formulates the desk's reallocation problem as a constrained linear program (scipy HiGHS). Maximizes net economics (fee revenue minus capital cost) subject to:

• Counterparty exposure limits
• Issuer concentration caps (max 15% of book NMV per issuer)
• Desk RWA budget (optional)
• Position-level move caps (risk control: max 100% of position per cycle)

Capital cost enters the objective directly via risk/capital_rwa.py — the optimizer is capital-aware by construction, not by post-hoc adjustment.

Outputs: REPRICE (same counterparty, market rate) and REROUTE (alternative counterparty) recommendations, ranked by P&L impact.

Classifies every security as GC → Warm → Specials-in-Waiting → Special → HTB → Deep Special based on market composite rate and utilization (EquiLend/DataLend). Computes a z-score of the desk's rate vs. market within the security's specialness tier — so a 5bp gap on a GC name scores very differently from a 5bp gap on a 4,000bp deep special.

Specials-in-Waiting (utilization >85%, fee not yet repriced) is the highest-value early detection signal — this is where the desk captures the spread before the market catches up.

Produces two independent scores per open settlement fail:

• Urgency (0-100): how soon someone needs to act
• Buy-in risk (0-100): likelihood this specific fail escalates to a forced buy-in

Buy-in risk uses a multiplicative model: base score (fail age vs. regime notice days) × specialness multiplier (1.5× for HTB, 2.2× for Deep Special) × substitute penalty (1.25× if no substitute inventory). Correctly distinguishes fail-to-deliver (the desk owes securities, the actually buy-in-able direction) from fail-to-receive.

Scores every rehypothecatable position by cheapest-to-deliver rank (equities → agency → gov → cash, weighted by opportunity cost and haircut burden). Identifies collateral substitution opportunities where a lower-cost eligible substitute exists in inventory, saving the annual opportunity cost of posting expensive HQLA when equities would satisfy the counterparty's schedule.

Intraday GREEN/AMBER/RED/BREACH dashboard. Includes simulate_incremental_exposure() — used by the optimization engine before proposing a REROUTE and exposed via the API for ad-hoc pre-trade checks. Uses gross MV (conservative, no haircut assumptions needed) rather than net exposure for monitoring, so the limit is never overstated as "safe" due to collateral assumptions being wrong intraday.

Four standard named scenarios (equity crash, repo rate spike, FX devaluation, combined regulatory stress) plus user-defined event scenarios. Reverse-stress analysis: find the minimum shock magnitude that breaches a configurable P&L loss threshold. All scenarios produce a ScenarioResult with consistent shape — the same fields regardless of scenario type.

Lifecycle-tracked pricing, limit, and data-quality exceptions: PROPOSED → APPROVED (ACTIVE) → CLOSED. Every exception requires a named approver (decided_by). Expired exceptions are detected automatically. Designed as an auditable override mechanism — exceptions are documented, not hidden.

Pandas-based matching on (security_internal_id, counterparty_id, trade_date, direction). Detects and classifies: quantity mismatch, price/rate mismatch, missing-at-custodian, missing-on-book, duplicate entries. Flags buy-in-risk-relevant and capital-misstatement-relevant breaks separately. Self-reconciliation produces zero breaks (regression-tested).

# Full test suite
PYTHONPATH=src:. python3 -m unittest discover -s tests -p "test_*.py"
# Expected: Ran 135 tests in ~0.5s, OK

# Unit tests only
PYTHONPATH=src:. python3 -m unittest discover -s tests/unit -p "test_*.py"

# Integration test only (full cycle, all engines wired together)
PYTHONPATH=src:. python3 -m unittest tests.integration.test_full_cycle -v

# With coverage (requires pytest, pip install -e ".[dev]")
pytest tests/ --cov=secfi_platform --cov-report=term-missing

Full validation plan: docs/testing_validation.md

This platform is advisory and analytical only. It does not trade, book, or execute anything without explicit human approval.

Recommendation generated (approval_status = PROPOSED)
         │
         ▼
Trader / risk manager reviews via dashboard or GET /v1/...
         │
         ▼
POST /v1/recommendations/approval-decision
     { decision: "APPROVE" | "REJECT", decided_by: "trader_id", comment: "..." }
         │
         ▼
Immutable audit record → secfi.recommendation_approval_log
         │  (if APPROVED)
         ▼
Human trader executes in the FIRM'S EXISTING trade booking system

No recommendation auto-approves. No endpoint auto-executes.

Model change governance checklist (required before merging any change to a risk/optimization/pricing module): see docs/model_risk.md.

CI gate: any PR touching risk/, optimization/, pricing/, or recall_buyin/ must contain MODEL_RISK_CHECKLIST_ACKNOWLEDGED in the PR description or the CI pipeline blocks merge.

See docs/governance.md for the full role matrix. Summary:

• Desk head, traders: full read access + approval-decision endpoint
• Risk managers: full read access, no approval authority (by this build's design — adjust per the firm's delegation-of-authority policy)
• Operations: reconciliation, settlement fails, recall queue
• Technology: health checks, observability
• Senior management: executive summary

Authentication/authorization is intentionally not implemented in this reference build — the firm's existing SSO/OAuth2 provider and API gateway should front this service. See docs/assumptions_and_limitations.md item ARCH-2.

Full list: docs/assumptions_and_limitations.md

Full runbook: docs/runbook.md

See docs/sample_outputs/daily_executive_summary_2026-06-18.md — produced by a real full-cycle run against the bundled fixtures, showing:

• Book NMV $116.6mm across 12 positions
• 4 reconciliation breaks (1 quantity mismatch P004, 1 price mismatch P009, 1 missing-at-custodian P010, 1 missing-on-book for CPTY004 position)
• GME (deep special, 6-day-old fail-to-deliver) at the top of the buy-in queue with buy-in risk 100/100
• 7 pricing recommendations with estimated P&L opportunities
• CPTY004 (watch-list counterparty) recommended REDUCE
• 3 corporate action watchlist items requiring desk action

[
  {
    "position_id": "P003",
    "ticker": "GME",
    "counterparty_id": "CPTY003",
    "urgency_score": 95.0,
    "buyin_risk_score": 100.0,
    "recommended_action": "RETURN",
    "drivers": [
      "Settlement fail aged 6 day(s); fail-to-deliver (desk owes).",
      "Locate shortage of 18000 shares against open requests.",
      "Security classified DEEP_SPECIAL; scarce replacement supply.",
      "Upcoming corporate action creates an imminent return obligation on this name."
    ]
  }
]

{
  "recommendation_id": "3f7a9b21-...",
  "action": "REPRICE",
  "target_id": "P003",
  "from_value": "300.00",
  "to_value": "2220.00",
  "estimated_pnl_impact_usd": "192455.00",
  "confidence": 0.865,
  "priority_score": 78.4,
  "approval_status": "PROPOSED",
  "rationale": [
    "GME is classified DEEP_SPECIAL (market weighted-avg 2220.0bps, desk rate 300.0bps, gap -1920.0bps).",
    "Estimated annualized P&L improvement from repricing: $192,455."
  ]
}

1. Create src/secfi_platform/<your_module>/<engine>.py
2. Import from common/types.py and explainability/explain.py — do not invent new output shapes
3. Emit Recommendation or Alert objects using the shared contract
4. Wire into orchestration/scheduler.py run_full_cycle() at the appropriate stage
5. Add an API endpoint in api/routers/desk.py or risk_extended.py
6. Write unit tests; run the full suite; confirm 0 regressions

1. Create a connector class in ingestion/connectors.py extending SourceConnector
2. Add a parse_* function in normalization/schema_mapping.py
3. Add the source name to ingestion.sources in configs/base.yaml
4. Wire into scripts/run_daily_batch.py _load_demo_dataset()
5. Add fixture CSV to tests/fixtures/ and update tests/_helpers.py

All risk/alert thresholds live in configs/base.yaml. Changes to these — including specialness tiers, growth/reduce thresholds, alert severity thresholds — are config changes, not code changes. They go through standard config version control but do NOT require the model-risk governance checklist.

• Model owner: Securities Finance Quant Engineering (assign before production deployment)
• Last validation date: Populate configs/prod.yaml governance.last_validation_date at each release
• Capital approximation: risk/capital_rwa.py is desk-decision-support only — never for regulatory reporting
• Model risk tier: High (optimization, buy-in scoring, capital approximation), Medium (pricing, growth, scenarios), Low (explainability scoring)

See docs/model_risk.md for the complete model inventory and governance checklist.

Built by Securities Finance Quant Engineering for the Global Securities Lending & Financing Desk, Prime Brokerage Division.