algo-cli-runtime 0.14.0__py3-none-any.whl

algo_cli/intelligence/finance/construction.py

@@ -0,0 +1,135 @@
+"""B96/B100/B101. Construction WIP, fixed assets, payroll reconciliations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from decimal import Decimal
+from typing import Any, Iterable
+
+from .common import ReviewGate, SourceRef, decimalize, stable_exception_id, within_tolerance
+
+
+@dataclass(frozen=True)
+class JobCost:
+    id: str
+    contract_value: Decimal | int | str
+    costs_to_date: Decimal | int | str
+    estimated_total_cost: Decimal | int | str
+    billed_to_date: Decimal | int | str
+    source_refs: list[SourceRef] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        for attr in ("contract_value", "costs_to_date", "estimated_total_cost", "billed_to_date"):
+            object.__setattr__(self, attr, decimalize(getattr(self, attr)))
+
+
+@dataclass(frozen=True)
+class WIPRow:
+    job_id: str
+    percent_complete: Decimal
+    earned_revenue: Decimal
+    billed_to_date: Decimal
+    over_under_billing: Decimal
+    source_refs: list[SourceRef]
+
+
+@dataclass(frozen=True)
+class WIPException:
+    id: str
+    job_id: str
+    amount: Decimal
+    message: str
+    source_refs: list[SourceRef]
+    review_gate: ReviewGate = ReviewGate.CONTROLLER_REVIEW
+
+
+@dataclass(frozen=True)
+class WIPReport:
+    rows: list[WIPRow]
+    total_over_under: Decimal
+    exceptions: list[WIPException]
+
+
+class ConstructionWIPController:
+    def compute_wip(self, jobs: Iterable[JobCost | dict[str, Any]], materiality: Decimal | int | str = Decimal("1000")) -> WIPReport:
+        rows: list[WIPRow] = []
+        exceptions: list[WIPException] = []
+        threshold = decimalize(materiality)
+        for job in [_coerce_job(row) for row in jobs]:
+            pct = Decimal("0") if job.estimated_total_cost == 0 else min(job.costs_to_date / job.estimated_total_cost, Decimal("1"))
+            earned = job.contract_value * pct
+            over_under = job.billed_to_date - earned
+            row = WIPRow(job.id, pct, earned, job.billed_to_date, over_under, list(job.source_refs))
+            rows.append(row)
+            if abs(over_under) >= threshold:
+                message = "overbilling" if over_under > 0 else "underbilling"
+                exceptions.append(WIPException(stable_exception_id("B96", [job.id, over_under]), job.id, over_under, message, list(job.source_refs)))
+        return WIPReport(rows=rows, total_over_under=sum((row.over_under_billing for row in rows), Decimal("0")), exceptions=exceptions)
+
+    def flag_over_under_billing(self, jobs: Iterable[JobCost | dict[str, Any]], materiality: Decimal | int | str = Decimal("1000")) -> list[WIPException]:
+        return self.compute_wip(jobs, materiality=materiality).exceptions
+
+
+@dataclass(frozen=True)
+class RollForwardResult:
+    clean: bool
+    beginning: Decimal
+    additions: Decimal
+    disposals: Decimal
+    depreciation: Decimal
+    ending: Decimal
+    expected_ending: Decimal
+    difference: Decimal
+    source_refs: list[SourceRef] = field(default_factory=list)
+
+
+class FixedAssetRollForward:
+    def roll_forward(
+        self,
+        assets: Iterable[dict[str, Any]],
+        additions: Iterable[dict[str, Any]],
+        disposals: Iterable[dict[str, Any]],
+        depreciation: Iterable[dict[str, Any]],
+        tolerance: Decimal | int | str = Decimal("0"),
+    ) -> RollForwardResult:
+        beginning = sum((decimalize(row.get("beginning_nbv", row.get("amount", 0))) for row in assets), Decimal("0"))
+        ending = sum((decimalize(row.get("ending_nbv", row.get("ending", row.get("amount", 0)))) for row in assets), Decimal("0"))
+        add = sum((decimalize(row.get("amount", 0)) for row in additions), Decimal("0"))
+        disp = sum((decimalize(row.get("amount", 0)) for row in disposals), Decimal("0"))
+        dep = sum((decimalize(row.get("amount", 0)) for row in depreciation), Decimal("0"))
+        expected = beginning + add - disp - dep
+        refs = [ref for row in [*assets, *additions, *disposals, *depreciation] for ref in row.get("source_refs", [])]
+        return RollForwardResult(within_tolerance(ending, expected, tolerance), beginning, add, disp, dep, ending, expected, ending - expected, refs)
+
+
+@dataclass(frozen=True)
+class PayrollReconResult:
+    clean: bool
+    register_total: Decimal
+    gl_total: Decimal
+    tax_liability_total: Decimal
+    differences: dict[str, Decimal]
+    source_refs: list[SourceRef]
+
+
+class PayrollReconciler:
+    def reconcile(
+        self,
+        payroll_register: Iterable[dict[str, Any]],
+        gl: Iterable[dict[str, Any]],
+        tax_liabilities: Iterable[dict[str, Any]],
+        tolerance: Decimal | int | str = Decimal("0"),
+    ) -> PayrollReconResult:
+        register_total = sum((decimalize(row.get("gross_pay", row.get("amount", 0))) for row in payroll_register), Decimal("0"))
+        gl_total = sum((decimalize(row.get("amount", 0)) for row in gl), Decimal("0"))
+        tax_total = sum((decimalize(row.get("amount", 0)) for row in tax_liabilities), Decimal("0"))
+        differences = {"register_to_gl": register_total - gl_total, "tax_liability": tax_total}
+        refs = [ref for row in [*payroll_register, *gl, *tax_liabilities] for ref in row.get("source_refs", [])]
+        clean = within_tolerance(register_total, gl_total, tolerance) and bool(tax_liabilities)
+        return PayrollReconResult(clean, register_total, gl_total, tax_total, differences, refs)
+
+
+def _coerce_job(row: JobCost | dict[str, Any]) -> JobCost:
+    if isinstance(row, JobCost):
+        return row
+    return JobCost(str(row["id"]), row.get("contract_value", 0), row.get("costs_to_date", 0), row.get("estimated_total_cost", 0), row.get("billed_to_date", 0), list(row.get("source_refs", [])))

algo_cli/intelligence/finance/controls.py

@@ -0,0 +1,172 @@
+"""B87. COSO Risk-Control Matrix Compiler."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from decimal import Decimal
+from typing import Iterable
+
+from .common import RiskLevel, Severity, SourceRef, stable_exception_id
+from .exceptions import make_exception
+
+
+@dataclass(frozen=True)
+class FinanceProcess:
+    id: str
+    name: str
+    owner: str | None = None
+    assertions: set[str] = field(default_factory=set)
+
+
+@dataclass(frozen=True)
+class Risk:
+    id: str
+    process_id: str
+    description: str
+    level: RiskLevel = RiskLevel.MEDIUM
+    assertion: str | None = None
+
+
+@dataclass(frozen=True)
+class Control:
+    id: str
+    process_id: str
+    description: str
+    covers_risk_ids: set[str] = field(default_factory=set)
+    owner: str | None = None
+    control_type: str = "detective"  # preventive, detective, corrective
+    frequency: str | None = None
+    evidence_required: str | None = None
+    automated: bool = False
+    key_control: bool = False
+    source_refs: list[SourceRef] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class RCMRow:
+    process: FinanceProcess
+    risk: Risk
+    controls: list[Control]
+    residual_level: RiskLevel
+    assertions: set[str]
+
+
+@dataclass
+class RiskControlMatrix:
+    rows: list[RCMRow]
+    control_count: int
+    risk_count: int
+
+    @property
+    def coverage_ratio(self) -> Decimal:
+        if not self.risk_count:
+            return Decimal("1")
+        covered = sum(1 for row in self.rows if row.controls)
+        return Decimal(covered) / Decimal(self.risk_count)
+
+
+@dataclass(frozen=True)
+class ControlGap:
+    id: str
+    risk_id: str | None
+    control_id: str | None
+    severity: Severity
+    message: str
+    source_refs: list[SourceRef] = field(default_factory=list)
+
+
+class RiskControlMatrixCompiler:
+    """Compile process/risk/control metadata into a controller RCM."""
+
+    def compile(
+        self,
+        processes: Iterable[FinanceProcess],
+        risks: Iterable[Risk],
+        controls: Iterable[Control],
+    ) -> RiskControlMatrix:
+        process_by_id = {process.id: process for process in processes}
+        controls_by_risk: dict[str, list[Control]] = {}
+        control_rows = list(controls)
+        for control in control_rows:
+            for risk_id in control.covers_risk_ids:
+                controls_by_risk.setdefault(risk_id, []).append(control)
+
+        rows: list[RCMRow] = []
+        risk_rows = list(risks)
+        for risk in risk_rows:
+            process = process_by_id.get(risk.process_id) or FinanceProcess(id=risk.process_id, name=risk.process_id)
+            covered_controls = sorted(controls_by_risk.get(risk.id, []), key=lambda c: c.id)
+            residual = _residual_level(risk.level, covered_controls)
+            assertions = set(process.assertions)
+            if risk.assertion:
+                assertions.add(risk.assertion)
+            rows.append(RCMRow(
+                process=process,
+                risk=risk,
+                controls=covered_controls,
+                residual_level=residual,
+                assertions=assertions,
+            ))
+        return RiskControlMatrix(rows=rows, control_count=len(control_rows), risk_count=len(risk_rows))
+
+    def find_gaps(self, matrix: RiskControlMatrix) -> list[ControlGap]:
+        gaps: list[ControlGap] = []
+        for row in matrix.rows:
+            if not row.controls:
+                gaps.append(ControlGap(
+                    id=stable_exception_id("B87", [row.risk.id, "no-control"]),
+                    risk_id=row.risk.id,
+                    control_id=None,
+                    severity=Severity.HIGH if row.risk.level >= RiskLevel.HIGH else Severity.MEDIUM,
+                    message=f"Risk {row.risk.id} has no mapped control",
+                ))
+                continue
+            if not any(control.control_type.lower() == "preventive" for control in row.controls):
+                gaps.append(ControlGap(
+                    id=stable_exception_id("B87", [row.risk.id, "no-preventive"]),
+                    risk_id=row.risk.id,
+                    control_id=None,
+                    severity=Severity.LOW,
+                    message=f"Risk {row.risk.id} has no preventive control",
+                ))
+            for control in row.controls:
+                if not control.owner:
+                    gaps.append(ControlGap(
+                        id=stable_exception_id("B87", [row.risk.id, control.id, "owner"]),
+                        risk_id=row.risk.id,
+                        control_id=control.id,
+                        severity=Severity.MEDIUM,
+                        message=f"Control {control.id} lacks an owner",
+                        source_refs=list(control.source_refs),
+                    ))
+                if control.key_control and not control.evidence_required:
+                    gaps.append(ControlGap(
+                        id=stable_exception_id("B87", [row.risk.id, control.id, "evidence"]),
+                        risk_id=row.risk.id,
+                        control_id=control.id,
+                        severity=Severity.HIGH,
+                        message=f"Key control {control.id} lacks evidence requirement",
+                        source_refs=list(control.source_refs),
+                    ))
+        return gaps
+
+    def exceptions_for_gaps(self, gaps: Iterable[ControlGap]):
+        return [
+            make_exception(
+                "B87",
+                gap.message,
+                severity=gap.severity,
+                tags={"control-gap", f"risk:{gap.risk_id}"} if gap.risk_id else {"control-gap"},
+                source_refs=gap.source_refs,
+            )
+            for gap in gaps
+        ]
+
+
+def _residual_level(level: RiskLevel, controls: list[Control]) -> RiskLevel:
+    if not controls:
+        return level
+    reduction = 1 if any(control.key_control for control in controls) else 0
+    if any(control.automated for control in controls):
+        reduction += 1
+    return RiskLevel(max(int(RiskLevel.LOW), int(level) - reduction))

algo_cli/intelligence/finance/evidence.py

@@ -0,0 +1,119 @@
+"""B103. Evidence Binder / PBC Indexer."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Iterable
+
+from .common import EvidenceItem, EvidenceStatus, SourceRef
+
+
+@dataclass
+class EvidenceRequest:
+    id: str
+    description: str
+    required: bool = True
+    evidence: list[EvidenceItem] = field(default_factory=list)
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    reviewed_at: datetime | None = None
+    expected_hashes: set[str] = field(default_factory=set)
+
+
+@dataclass
+class EvidenceReport:
+    total_requests: int
+    complete_count: int
+    missing_count: int
+    stale_count: int
+    open_ids: list[str]
+    stale_ids: list[str]
+
+    @property
+    def complete(self) -> bool:
+        return self.missing_count == 0 and self.stale_count == 0
+
+
+class EvidenceBinder:
+    """Indexes support for workpapers/PBC requests with source hashes."""
+
+    def __init__(self) -> None:
+        self.requests: dict[str, EvidenceRequest] = {}
+
+    def add_request(self, request_id: str, description: str, required: bool = True) -> EvidenceRequest:
+        request = EvidenceRequest(id=request_id, description=description, required=required)
+        self.requests[request_id] = request
+        return request
+
+    def attach_evidence(
+        self,
+        request_id: str,
+        item_id: str,
+        description: str,
+        source_refs: Iterable[SourceRef],
+        prepared_by: str | None = None,
+    ) -> EvidenceItem:
+        request = self.requests[request_id]
+        item = EvidenceItem(
+            id=item_id,
+            description=description,
+            source_refs=list(source_refs),
+            prepared_by=prepared_by,
+            status=EvidenceStatus.RECEIVED,
+        )
+        request.evidence.append(item)
+        return item
+
+    def mark_reviewed(self, request_id: str, reviewer: str) -> None:
+        request = self.requests[request_id]
+        request.expected_hashes = {
+            ref.document_hash
+            for item in request.evidence
+            for ref in item.source_refs
+            if ref.document_hash
+        }
+        for item in request.evidence:
+            item.reviewed_by = reviewer
+            item.status = EvidenceStatus.REVIEWED
+        request.reviewed_at = datetime.now(timezone.utc)
+
+    def refresh_stale_status(self) -> list[str]:
+        stale_ids: list[str] = []
+        for request in self.requests.values():
+            if not request.expected_hashes:
+                continue
+            current_hashes = {
+                ref.document_hash
+                for item in request.evidence
+                for ref in item.source_refs
+                if ref.document_hash
+            }
+            if current_hashes != request.expected_hashes:
+                stale_ids.append(request.id)
+                for item in request.evidence:
+                    item.status = EvidenceStatus.STALE
+        return stale_ids
+
+    def completeness_report(self) -> EvidenceReport:
+        stale_ids = self.refresh_stale_status()
+        open_ids: list[str] = []
+        complete_count = 0
+        missing_count = 0
+        for request in self.requests.values():
+            has_support = any(item.has_support for item in request.evidence)
+            reviewed_or_received = any(
+                item.status in (EvidenceStatus.RECEIVED, EvidenceStatus.REVIEWED) for item in request.evidence
+            )
+            if request.required and not (has_support and reviewed_or_received):
+                missing_count += 1
+                open_ids.append(request.id)
+            else:
+                complete_count += 1
+        return EvidenceReport(
+            total_requests=len(self.requests),
+            complete_count=complete_count,
+            missing_count=missing_count,
+            stale_count=len(stale_ids),
+            open_ids=open_ids,
+            stale_ids=stale_ids,
+        )

algo_cli/intelligence/finance/exceptions.py

@@ -0,0 +1,157 @@
+"""B105. Controller Exception Queue with Materiality Gate."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date
+from decimal import Decimal
+from typing import Iterable
+
+from .common import FinanceException, MaterialityPolicy, ReviewGate, Severity, stable_exception_id
+
+
+@dataclass
+class ExceptionCluster:
+    key: str
+    exceptions: list[FinanceException]
+    highest_severity: Severity
+    total_amount: Decimal
+    representative: FinanceException
+
+
+@dataclass
+class WaiverResult:
+    approved: bool
+    exception: FinanceException
+    message: str
+
+
+@dataclass
+class QueueSummary:
+    total: int
+    open_count: int
+    waived_count: int
+    requires_review_count: int
+    by_pattern: dict[str, int] = field(default_factory=dict)
+
+
+class ControllerExceptionQueue:
+    """Finite controller queue that ranks exceptions by materiality and risk.
+
+    This queue is intentionally non-mutating with respect to accounting systems:
+    it routes review work and waiver metadata only.  It never posts entries,
+    approves payments, or sends external communications.
+    """
+
+    def __init__(self) -> None:
+        self._exceptions: dict[str, FinanceException] = {}
+
+    def add(self, exception: FinanceException) -> None:
+        self._exceptions[exception.id] = exception
+
+    def extend(self, exceptions: Iterable[FinanceException]) -> None:
+        for exception in exceptions:
+            self.add(exception)
+
+    def all(self) -> list[FinanceException]:
+        return list(self._exceptions.values())
+
+    def rank(
+        self,
+        materiality_policy: MaterialityPolicy | None = None,
+        as_of: date | None = None,
+        include_waived: bool = False,
+    ) -> list[FinanceException]:
+        policy = materiality_policy or MaterialityPolicy()
+        rows = [ex for ex in self._exceptions.values() if include_waived or not ex.waived]
+        return sorted(
+            rows,
+            key=lambda ex: (
+                policy.score_exception(ex, as_of=as_of),
+                int(ex.severity),
+                abs(ex.amount or Decimal("0")),
+                ex.id,
+            ),
+            reverse=True,
+        )
+
+    def cluster_duplicates(self) -> list[ExceptionCluster]:
+        clusters: dict[str, list[FinanceException]] = {}
+        for exception in self._exceptions.values():
+            key = _cluster_key(exception)
+            clusters.setdefault(key, []).append(exception)
+
+        out: list[ExceptionCluster] = []
+        for key, exceptions in clusters.items():
+            total = sum((abs(ex.amount or Decimal("0")) for ex in exceptions), Decimal("0"))
+            representative = sorted(
+                exceptions,
+                key=lambda ex: (int(ex.severity), abs(ex.amount or Decimal("0")), ex.id),
+                reverse=True,
+            )[0]
+            out.append(ExceptionCluster(
+                key=key,
+                exceptions=exceptions,
+                highest_severity=max((ex.severity for ex in exceptions), default=Severity.INFO),
+                total_amount=total,
+                representative=representative,
+            ))
+        return sorted(out, key=lambda c: (len(c.exceptions), int(c.highest_severity), c.total_amount), reverse=True)
+
+    def require_approval_for_waiver(
+        self,
+        exception_id: str,
+        rationale: str | None,
+        approver: str | None,
+        expires: date | None,
+    ) -> WaiverResult:
+        exception = self._exceptions[exception_id]
+        if not rationale or not approver or expires is None:
+            return WaiverResult(False, exception, "Waiver requires rationale, approver, and expiration period.")
+        exception.waived = True
+        exception.waiver_rationale = rationale
+        exception.waiver_approver = approver
+        exception.waiver_expires = expires
+        exception.review_gate = ReviewGate.CONTROLLER_REVIEW
+        return WaiverResult(True, exception, "Waiver recorded for controller review trail.")
+
+    def summary(self) -> QueueSummary:
+        by_pattern: dict[str, int] = {}
+        for exception in self._exceptions.values():
+            by_pattern[exception.pattern_id] = by_pattern.get(exception.pattern_id, 0) + 1
+        return QueueSummary(
+            total=len(self._exceptions),
+            open_count=sum(1 for ex in self._exceptions.values() if not ex.waived),
+            waived_count=sum(1 for ex in self._exceptions.values() if ex.waived),
+            requires_review_count=sum(1 for ex in self._exceptions.values() if ex.requires_human_review),
+            by_pattern=by_pattern,
+        )
+
+
+def make_exception(
+    pattern_id: str,
+    message: str,
+    severity: Severity = Severity.MEDIUM,
+    amount: Decimal | int | str | None = None,
+    tags: Iterable[str] = (),
+    source_refs=None,
+) -> FinanceException:
+    key = [pattern_id, message, str(amount), sorted(str(tag).lower() for tag in tags)]
+    return FinanceException(
+        id=stable_exception_id(pattern_id, key),
+        pattern_id=pattern_id,
+        severity=severity,
+        amount=amount,
+        message=message,
+        source_refs=list(source_refs or []),
+        tags=set(tags),
+    )
+
+
+def _cluster_key(exception: FinanceException) -> str:
+    root_tags = sorted(tag for tag in exception.tags if tag.startswith("root:") or tag.startswith("account:"))
+    if root_tags:
+        return "|".join([exception.pattern_id, *root_tags])
+    source_ids = sorted(ref.source_id for ref in exception.source_refs)
+    normalized_message = " ".join(exception.message.lower().split()[:8])
+    return "|".join([exception.pattern_id, normalized_message, *source_ids])