maat library

The agent-orchestration library (libs/maat/agents/src, ~28 modules, ~27.8K LOC — the largest in the area). It implements an agent platform: a registry (agent-registry.ts with typed implementation handlers, health-check handlers, and ACTIVE/INACTIVE/RETIRING/DEPRECATED lifecycle states), a factory, lifecycle/pool managers, and a configuration schema, plus role agents (strategy, engineering, finance, operations, research, compliance). The coordination layer adds a task decomposer, dependency-graph executor, a tool registry, MCP server-discovery / transaction-coordinator / intent-routing, inter-agent communication, an agent memory system, a human-in-the-loop workflow engine, performance-tracking and feedback-loop systems, an observability dashboard, a LangGraph-style workflow engine, an RL capital-allocation environment, and a federated-learning framework. Note: this is the in-process agent infrastructure/data-model layer; LLM/tool execution is handled through the typed handler and provider seams rather than a bundled model client.

The capital-allocation library (libs/maat/capital/src, ~16 modules, ~9K LOC). It implements portfolio and investment decision tooling: a Black-Litterman allocator (black-litterman.ts, with a confidence→omega mapping over LOW… VERY_HIGH views and absolute/relative view types), investment evaluation, hurdle-rate and capital-budgeting engines, a funding waterfall, debt-capacity and treasury management, and Africa-specific instruments — diaspora-investment, impact-investment, government-incentive, and milestone-capital-release modules, plus capital-call management and a capital-efficiency dashboard. Results are hash-stamped via @noble/hashes for auditability.

The regulatory-compliance library (libs/maat/compliance/src, ~21 modules, ~21K LOC) built around Ghana law. It carries a Ghana regulatory-body registry, a Ghana regulation catalog, and a requirement-mapping engine, plus license/permit tracking, a compliance calendar, regulatory-change monitoring, gap analysis, audit preparation, and a cross-jurisdiction mapper. Domain-specific frameworks include anti-corruption compliance, ESG reporting, environmental-impact assessment, governance-compliance tracking, supply-chain ethics monitoring, a Ghana Data Protection Act compliance engine, IP-portfolio management, contract-compliance monitoring, regulatory-filing automation, and compliance-training management.

The foundation tier (libs/maat/core/src, maat:tier:core). It owns the shared organisation model in organization.ts — branded ID types (OrganizationId, OperatingCompanyId, ISODateString), and the enums every other Maat library keys off (LEGAL_ENTITY_TYPE_VALUES, LEGAL_STRUCTURE_MODEL_VALUES, OWNERSHIP_MODEL_VALUES, OPERATING_COMPANY_INDUSTRY_SECTOR_VALUES) — plus the typed event bus in event-bus.ts (the MaatDomainEventTypeSchema enum of MarketIntelligenceEvent/AgentTaskEvent/StrategyDecisionEvent/ ComplianceAlertEvent/SimulationStateEvent with versioned, correlation-stamped Zod payloads) and Redis namespace conventions in redis-namespace.ts. Four real implementation modules; the barrel re-exports all three.

A narrow, single-purpose library (libs/maat/dashboard/src, ~93 LOC — two modules, one real). It builds the governed V2 balance dashboard surface (v2-balance-dashboard.ts): a manifest of panels (pick-rate, win-rate, win-rate-on-block, frame-data-drift, hot/cold heatmap, A/B publication, release gate) bound to a fixed set of V2 match-event topics, that composes @maat/reporting charts and @maat/intelligence signals. package.json describes it as the home for "governed dashboard manifests and product-facing metric surfaces." Real and implemented, but deliberately scoped to the V2 balance surface rather than a general dashboard framework.

The organisation-simulation library (libs/maat/digital-twin/src, ~21 modules, ~22.4K LOC). It models the whole conglomerate as a digital twin: an organisation-state model (organization-state-model.ts with FINANCIAL/ PRODUCTION/INVENTORY/WORKFORCE/DEMAND/PROJECTS state dimensions across operating-company and business-unit scopes), a state-ingestion pipeline, snapshot versioning, a diff engine, and data-quality monitoring. On top sit simulation engines — business-unit dependency graph, what-if and bottleneck-identification analysis, impact attribution, temporal/facility/workforce/financial-cascade simulators, a market-shock simulator, multi-objective optimisation and resource-reallocation, a visualisation-data generator, a scenario manager, and a unifying simulation API.

The corporate-finance engine set (libs/maat/finance/src, ~22 modules, ~18K LOC). package.json describes it as "V2 ledger reconciliation, regional pricing, refunds, and regulatory caps," but the implemented surface is broader valuation/FP&A machinery: a real discounted-cash-flow engine (discounted-cash-flow-engine.ts with explicit GhanaMarketAssumptions — 91-day T-bill risk-free rate, frontier equity risk premium, country risk premium — WACC build-up and terminal value), comparable-company and LBO model builders, IRR/NPV, pro-forma income-statement and balance-sheet builders, FX-risk and multi-currency-consolidation engines, transfer pricing, and Ghana tax-optimisation and tax-calendar engines. The barrel also exports a v2-persistence-ledger.

The portfolio-integration layer (libs/maat/integrations/src, 8 modules, ~5.5K LOC). Its index.ts declares it "Connects all 7 Maat portfolio companies to the Maat intelligence platform," with one adapter per sibling domain: Asase (agriculture/cold-chain — commodity price points across COCOA/CASSAVA/MAIZE/etc. with COCOBOD/MOFA/FAO sources, supply-demand snapshots), Freya, Cybele, Brigid, Saraswati, Iris, and Aje. Each adapter defines the typed data shapes Maat ingests from that company into its intelligence, digital-twin, and finance models — the boundary translation layer between the operating companies and the Maat brain.

The market/competitive-intelligence library (libs/maat/intelligence/src, ~31 modules, ~24.7K LOC — the largest feature lib). package.json: "market, operational, anomaly, trend, and causal analysis." It implements a market monitor, news aggregator, web-scraping and streaming-ingestion framework, data-normalisation pipeline, competitor tracker and competitive-positioning engine, patent monitoring, supplier-intelligence, partnership/M&A radar, sentiment analyzer, trend detector, anomaly detection, and an early-warning system. The advanced surface adds a causal-inference engine, a world-model simulator, an intelligence synthesizer, a confidence-scoring framework, an NL2SQL and voice-command interface, multimodal-intelligence fusion, a predictive supply-chain twin, and an AI-regulatory-compliance scanner.

The knowledge-management / RAG library (libs/maat/knowledge/src, ~22 modules, ~20K LOC). It implements a document pipeline (ingestion, classification, summarisation, entity extraction, versioning/deduplication) feeding a Neo4j-schema knowledge graph with population, enrichment, query, and maintenance services, semantic search, and a research-corpus manager. Its headline component is a GraphRAG engine (graph-rag-engine.ts) explicitly following the Microsoft GraphRAG paper (Edge et al., 2024) — graph construction, Leiden-style community detection, community summarisation, and LOCAL/GLOBAL/HYBRID query modes over a Maat-business entity type set — with all embedding/LLM/graph I/O behind pluggable providers so it is testable in-memory. Also includes a patent-landscape engine, academic-research monitor, knowledge-freshness engine, and conflict resolution.

A narrow, single-purpose library (libs/maat/negotiation-intelligence/src, ~178 LOC — one real module). package.json: "Pactum-class procurement negotiation intelligence — supplier scoring, lever calibration, ERP bridge (Phase 179.7.1)." The implemented surface is the procurement-program.ts module: Zod schemas for a ProcurementProgram (procurement tracks like tail_spend_automated/direct_material_sourcing, an authorised lever set such as unit_price/payment_terms_dpo/rebate_tiered, and spend-based approval thresholds), plus findApprovalThreshold and toMaatExtensionDefaults helpers that translate a tenant program into the MaatProcurementExtension defaults each Concordia procurement case inherits. It is the tenant-config bridge to the Concordia negotiation domain — real and focused, with the broader supplier-scoring machinery described in the package description not yet present in src.

The portfolio/PMO library (libs/maat/projects/src, ~16 modules, ~10.7K LOC). It implements project and portfolio management as computational engines: project creation, a Gantt engine, cross-company dependency tracking, resource-allocation optimisation, earned-value management, and project-health scoring — plus a genetic portfolio optimiser (portfolio-genetic-optimizer.ts, which selects an active project set under resource constraints from typed PgoProject/PgoResourceDemand inputs weighted by priority and strategic value). Rounded out by a project-risk register, RACI-matrix generator, milestone-payment tracker, status reporting, change-request management, a lessons-learned database, a portfolio dashboard, and a project-template library.

The reporting/output library (libs/maat/reporting/src, ~16 modules, ~6.7K LOC). package.json: "KPI scorecards, charts, board packs, and governed report exports." It implements a KPI-scorecard engine (kpi-scorecard-engine.ts with RAG status, trend direction, variance-from-target and sparkline data across five strategic pillars — Financial/Operational/Customer/People/Sustainability), board-report and investor-deck generators, a chart-data generator, PDF-export engine, report distribution, an NL query interface, cross-company benchmarking, variance analysis, regulatory-filing reports, an MD&A commentary generator, an ad-hoc report builder, a cash-flow waterfall, and an ESG-report generator.

The enterprise-risk library (libs/maat/risk/src, ~16 modules, ~14.6K LOC). It implements a risk taxonomy and probability-impact framework plus quantitative risk math: a value-at-risk engine (value-at-risk.ts supporting PARAMETRIC, HISTORICAL, and MONTE_CARLO methods across confidence levels 0.90–0.999 and 1–252-day horizons, with a West-African currency set centred on GHS), portfolio Monte-Carlo, and key-risk-indicator tracking. Domain risk modules cover political, currency-hedging, commodity-price, cybersecurity, climate, and supply-chain risk, plus business-continuity, insurance-portfolio, emerging-risk-radar, and risk-appetite. Outputs are hash-stamped for an auditable risk register.

The client SDK (libs/maat/sdk/src, ~11 modules, ~5.7K LOC; maat:tier:sdk). It exposes the @maat/* platform to external consumers with Ghana-aware defaults (GHS currency, Africa/Accra timezone): a typed client (typed-client.ts with a MaatModule union over all fifteen feature modules, environment/retry/timeout config), a CLI tool, React components, a webhook manager, an API-key manager, batch operations, SSE streaming, a plugin architecture, an offline mode, and an SDK docs generator. It is the public-facing surface tier, not a feature engine.

The strategic-planning engine set (libs/maat/strategy/src, ~22 modules, ~17K LOC; maat:tier:feature). package.json: "strategic planning, capital allocation, and live-ops calendar authority." It implements the classic strategy frameworks as real analyzers — Porter's Five Forces, SWOT, TAM/SAM/SOM, BCG growth-share, Ansoff, Blue Ocean — alongside quantitative decision tooling: real-options valuation, a game-theory module, Monte-Carlo simulation, scenario definition/comparison, sensitivity and stress-testing frameworks, an MPT optimizer, and dynamic capital-reallocation. It also carries a domain-specific v2-fighting-game-live-ops-calendar (the "live-ops calendar authority" from the description), tying the strategy layer to the V2 game's release cadence.

The supply-chain and trade library (libs/maat/supply-chain/src, ~21 modules, ~21K LOC). Beyond standard supplier-map, supplier-risk-scoring, qualification/ onboarding, inventory-optimisation, logistics-routing, landed-cost, and demand-forecasting engines, its distinguishing feature is real West-African trade machinery: an AfCFTA tariff-optimisation engine (afcfta-tariff-optimization-engine.ts encoding the full African country-code set), an ECOWAS-CET database, free-trade-zone optimisation, customs-documentation generation, and a trade-finance intelligence module. There is also a supply-chain disruption simulator and a make-vs-buy analysis framework.

The people/HR-analytics library (libs/maat/workforce/src, ~16 modules, ~5.2K LOC). It models the workforce as decision-support engines rather than an HRIS: org-design modelling, headcount planning, skills-gap analysis, compensation-benchmarking, succession planning, and an attrition-prediction model (attrition-prediction.ts that scores flight risk from tenure, engagement, salary-vs-market, manager/peer relationship and job-search signals, weighting in Ghana-region and competitor-hiring intensity, and emits replacement-cost estimates in GHS). Also covers labour-market intelligence, payroll modelling, diversity-tracking, org-network analysis, contractor optimisation, expatriate management, training-ROI, and a workforce scenario planner.