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

algo_cli/intelligence/falsification_suite.py

@@ -0,0 +1,178 @@
+"""H20 — Falsification Suite.
+
+Multiple independent attack vectors on a claim.
+Mined from GLOSSOPETRAE experiments/falsify/ (S1-S4 probes).
+
+Each probe attacks the claim from a different angle. If any probe
+succeeds in falsifying the claim, the claim is rejected.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+@dataclass
+class FalsificationProbe:
+    """A single falsification probe."""
+
+    name: str
+    description: str
+    attack_fn: Callable[[dict[str, Any]], bool]  # Returns True if falsified
+
+
+@dataclass
+class ProbeResult:
+    """Result of a single probe."""
+
+    probe_name: str
+    falsified: bool
+    evidence: str = ""
+
+
+@dataclass
+class FalsificationResult:
+    """Combined result of all probes."""
+
+    entry_id: str
+    probe_results: list[ProbeResult] = field(default_factory=list)
+    any_falsified: bool = False
+    falsified_by: list[str] = field(default_factory=list)
+    survived_count: int = 0
+    total_count: int = 0
+
+
+# Built-in probes
+def probe_missing_evidence(entry_id: str, claims: dict[str, Any]) -> ProbeResult:
+    """S1: Check if claims lack evidence."""
+    falsified = False
+    evidence_parts: list[str] = []
+
+    for key, value in claims.items():
+        if value is None:
+            falsified = True
+            evidence_parts.append(f"{key} is None")
+        elif isinstance(value, (list, dict)) and len(value) == 0:
+            falsified = True
+            evidence_parts.append(f"{key} is empty")
+
+    return ProbeResult(
+        probe_name="missing-evidence",
+        falsified=falsified,
+        evidence="; ".join(evidence_parts) if evidence_parts else "All claims have values",
+    )
+
+
+def probe_contradictory_claims(entry_id: str, claims: dict[str, Any]) -> ProbeResult:
+    """S2: Check for internal contradictions."""
+    falsified = False
+    evidence_parts: list[str] = []
+
+    # Check status vs tests
+    status = claims.get("status", "")
+    tests = claims.get("tests", [])
+    if status == "implemented" and not tests:
+        falsified = True
+        evidence_parts.append("Status 'implemented' but no tests")
+
+    # Check score vs status
+    score = claims.get("score", 0.0)
+    if status == "implemented" and isinstance(score, (int, float)) and score < 0.5:
+        falsified = True
+        evidence_parts.append(f"Status 'implemented' but score={score}")
+
+    return ProbeResult(
+        probe_name="contradictory-claims",
+        falsified=falsified,
+        evidence="; ".join(evidence_parts) if evidence_parts else "No contradictions found",
+    )
+
+
+def probe_boundary_values(entry_id: str, claims: dict[str, Any]) -> ProbeResult:
+    """S3: Check for impossible boundary values."""
+    falsified = False
+    evidence_parts: list[str] = []
+
+    for key, value in claims.items():
+        if isinstance(value, (int, float)):
+            if value < 0.0 and "count" in key.lower():
+                falsified = True
+                evidence_parts.append(f"{key}={value} is negative")
+            if value > 1.0 and "rate" in key.lower():
+                falsified = True
+                evidence_parts.append(f"{key}={value} exceeds 1.0")
+
+    return ProbeResult(
+        probe_name="boundary-values",
+        falsified=falsified,
+        evidence="; ".join(evidence_parts) if evidence_parts else "All values in bounds",
+    )
+
+
+def probe_unverifiable_sources(entry_id: str, claims: dict[str, Any]) -> ProbeResult:
+    """S4: Check if sources are unverifiable."""
+    falsified = False
+    evidence_parts: list[str] = []
+
+    source = claims.get("source", "")
+    if source is None:
+        falsified = True
+        evidence_parts.append("Source is None")
+    elif not isinstance(source, str):
+        falsified = True
+        evidence_parts.append("Source is not a string")
+    elif not source.strip():
+        falsified = True
+        evidence_parts.append("Source is empty string")
+
+    return ProbeResult(
+        probe_name="unverifiable-sources",
+        falsified=falsified,
+        evidence="; ".join(evidence_parts) if evidence_parts else "Sources verifiable",
+    )
+
+
+# Default probe set
+DEFAULT_PROBES: list[tuple[str, Callable[[str, dict], ProbeResult]]] = [
+    ("missing-evidence", probe_missing_evidence),
+    ("contradictory-claims", probe_contradictory_claims),
+    ("boundary-values", probe_boundary_values),
+    ("unverifiable-sources", probe_unverifiable_sources),
+]
+
+
+def run_falsification(
+    entry_id: str,
+    claims: dict[str, Any],
+    probes: list[tuple[str, Callable[[str, dict], ProbeResult]]] | None = None,
+    model_client: Any | None = None,
+) -> FalsificationResult:
+    """Run a falsification suite against a claim set.
+
+    Args:
+        entry_id: The entry being tested.
+        claims: The claims to falsify.
+        probes: List of (name, probe_fn) tuples. Defaults to built-in probes.
+        model_client: Optional LLM for deeper probes.
+
+    Returns:
+        FalsificationResult with all probe results.
+    """
+    probe_list = probes or DEFAULT_PROBES
+    results: list[ProbeResult] = []
+
+    for name, fn in probe_list:
+        result = fn(entry_id, claims)
+        results.append(result)
+
+    falsified_by = [r.probe_name for r in results if r.falsified]
+    survived = sum(1 for r in results if not r.falsified)
+
+    return FalsificationResult(
+        entry_id=entry_id,
+        probe_results=results,
+        any_falsified=len(falsified_by) > 0,
+        falsified_by=falsified_by,
+        survived_count=survived,
+        total_count=len(results),
+    )

algo_cli/intelligence/finance/__init__.py

@@ -0,0 +1,169 @@
+"""Finance / CPA / Controller intelligence patterns B87-B105."""
+
+from .anomalies import JournalEntry, JournalEntryAnomalyScorer, JournalEntryScore
+from .ap_ar import (
+    APDuplicateDetector,
+    APInvoice,
+    APPayment,
+    ARAgingPrioritizer,
+    ARInvoice,
+    AgingBucket,
+    AgingReport,
+    CollectionAction,
+    DuplicateCandidate,
+    SoDConflict,
+    ThreeWayMatchResult,
+    Vendor,
+    VendorChangeEvent,
+    VendorRisk,
+    VendorRiskAnalyzer,
+)
+from .cash import CashFlowItem, CashForecast, CashForecastWeek, ForecastVariance, ForecastVarianceReport, ThirteenWeekCashForecast
+from .close import (
+    AccrualEngine,
+    AccrualPolicy,
+    AccrualProposal,
+    BlockedTask,
+    CloseDAG,
+    ClosePackageAnalyzer,
+    ClosePackageInputs,
+    ClosePackageResult,
+    CloseTask,
+    ReversalProposal,
+    Variance,
+    VarianceExplanation,
+    VarianceExplanationMiner,
+)
+from .common import (
+    EvidenceItem,
+    EvidenceStatus,
+    FinanceException,
+    MaterialityPolicy,
+    Money,
+    ReviewGate,
+    RiskLevel,
+    Severity,
+    SourceRef,
+    decimalize,
+    hash_source_bytes,
+    month_bucket,
+    normalize_invoice_number,
+    normalize_vendor_name,
+    stable_exception_id,
+    within_tolerance,
+)
+from .construction import (
+    ConstructionWIPController,
+    FixedAssetRollForward,
+    JobCost,
+    PayrollReconResult,
+    PayrollReconciler,
+    RollForwardResult,
+    WIPException,
+    WIPReport,
+    WIPRow,
+)
+from .controls import Control, ControlGap, FinanceProcess, RCMRow, Risk, RiskControlMatrix, RiskControlMatrixCompiler
+from .evidence import EvidenceBinder, EvidenceReport, EvidenceRequest
+from .exceptions import ControllerExceptionQueue, ExceptionCluster, QueueSummary, WaiverResult, make_exception
+from .reconciliations import BankItem, BankMatch, BankMatcher, MatchResult, ReconciliationAccount, ReconciliationTriage, RiskScore
+from .revenue import ASC606DecisionDAG, PerformanceObligation, RevenueContract, RevenueDecision
+from .tax import SalesUseTaxClassifier, TaxClassification, TaxLineResult, TaxPolicy
+from .workpapers import TieOutResult, WorkpaperTieOut
+
+__all__ = [
+    "JournalEntry",
+    "JournalEntryAnomalyScorer",
+    "JournalEntryScore",
+    "APDuplicateDetector",
+    "APInvoice",
+    "APPayment",
+    "ARAgingPrioritizer",
+    "ARInvoice",
+    "AgingBucket",
+    "AgingReport",
+    "CollectionAction",
+    "DuplicateCandidate",
+    "SoDConflict",
+    "ThreeWayMatchResult",
+    "Vendor",
+    "VendorChangeEvent",
+    "VendorRisk",
+    "VendorRiskAnalyzer",
+    "CashFlowItem",
+    "CashForecast",
+    "CashForecastWeek",
+    "ForecastVariance",
+    "ForecastVarianceReport",
+    "ThirteenWeekCashForecast",
+    "AccrualEngine",
+    "AccrualPolicy",
+    "AccrualProposal",
+    "BlockedTask",
+    "CloseDAG",
+    "ClosePackageAnalyzer",
+    "ClosePackageInputs",
+    "ClosePackageResult",
+    "CloseTask",
+    "ReversalProposal",
+    "Variance",
+    "VarianceExplanation",
+    "VarianceExplanationMiner",
+    "EvidenceItem",
+    "EvidenceStatus",
+    "FinanceException",
+    "MaterialityPolicy",
+    "Money",
+    "ReviewGate",
+    "RiskLevel",
+    "Severity",
+    "SourceRef",
+    "decimalize",
+    "hash_source_bytes",
+    "month_bucket",
+    "normalize_invoice_number",
+    "normalize_vendor_name",
+    "stable_exception_id",
+    "within_tolerance",
+    "ConstructionWIPController",
+    "FixedAssetRollForward",
+    "JobCost",
+    "PayrollReconResult",
+    "PayrollReconciler",
+    "RollForwardResult",
+    "WIPException",
+    "WIPReport",
+    "WIPRow",
+    "Control",
+    "ControlGap",
+    "FinanceProcess",
+    "RCMRow",
+    "Risk",
+    "RiskControlMatrix",
+    "RiskControlMatrixCompiler",
+    "EvidenceBinder",
+    "EvidenceReport",
+    "EvidenceRequest",
+    "ControllerExceptionQueue",
+    "ExceptionCluster",
+    "QueueSummary",
+    "WaiverResult",
+    "make_exception",
+    "BankItem",
+    "BankMatch",
+    "BankMatcher",
+    "MatchResult",
+    "ReconciliationAccount",
+    "ReconciliationTriage",
+    "RiskScore",
+    "ASC606DecisionDAG",
+    "PerformanceObligation",
+    "RevenueContract",
+    "RevenueDecision",
+    "SalesUseTaxClassifier",
+    "TaxClassification",
+    "TaxLineResult",
+    "TaxPolicy",
+    "TieOutResult",
+    "WorkpaperTieOut",
+]

algo_cli/intelligence/finance/anomalies.py

@@ -0,0 +1,135 @@
+"""B90. Journal Entry Anomaly Scoring."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date, datetime, time
+from decimal import Decimal
+from statistics import median
+from typing import Any, Iterable
+
+from .common import ReviewGate, RiskLevel, SourceRef, decimalize
+
+
+@dataclass(frozen=True)
+class JournalEntry:
+    id: str
+    account: str
+    amount: Decimal | int | str
+    entry_date: date | str
+    user: str
+    description: str = ""
+    manual: bool = True
+    approved_by: str | None = None
+    posted_at: datetime | str | None = None
+    source_refs: list[SourceRef] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "amount", decimalize(self.amount))
+        if isinstance(self.entry_date, str):
+            object.__setattr__(self, "entry_date", datetime.fromisoformat(self.entry_date[:10]).date())
+        if isinstance(self.posted_at, str):
+            object.__setattr__(self, "posted_at", datetime.fromisoformat(self.posted_at))
+
+
+@dataclass(frozen=True)
+class JournalEntryScore:
+    entry: JournalEntry
+    score: Decimal
+    level: RiskLevel
+    reasons: list[str]
+    source_refs: list[SourceRef]
+    review_gate: ReviewGate = ReviewGate.CONTROLLER_REVIEW
+
+
+class JournalEntryAnomalyScorer:
+    """Weighted JE risk scoring for controller review, not auto-rejection."""
+
+    def score(
+        self,
+        entries: Iterable[JournalEntry | dict[str, Any]],
+        history: Iterable[JournalEntry | dict[str, Any]] | None = None,
+    ) -> list[JournalEntryScore]:
+        rows = [_coerce_entry(entry) for entry in entries]
+        hist = [_coerce_entry(entry) for entry in (history or [])]
+        account_medians = _median_amount_by_account(hist)
+        user_accounts = _accounts_by_user(hist)
+        scored = [self._score_one(entry, account_medians, user_accounts) for entry in rows]
+        return sorted(scored, key=lambda row: (row.score, abs(row.entry.amount), row.entry.id), reverse=True)
+
+    def _score_one(
+        self,
+        entry: JournalEntry,
+        account_medians: dict[str, Decimal],
+        user_accounts: dict[str, set[str]],
+    ) -> JournalEntryScore:
+        score = Decimal("0")
+        reasons: list[str] = []
+        amount = abs(entry.amount)
+        if entry.manual:
+            score += Decimal("100")
+            reasons.append("manual entry")
+        if not entry.approved_by:
+            score += Decimal("300")
+            reasons.append("missing approval")
+        if _is_round_amount(amount):
+            score += Decimal("125")
+            reasons.append("round-dollar amount")
+        if entry.posted_at and _outside_business_hours(entry.posted_at):
+            score += Decimal("175")
+            reasons.append("posted outside business hours")
+        if entry.entry_date.day >= 28:
+            score += Decimal("100")
+            reasons.append("period-end posting")
+        if not entry.description.strip():
+            score += Decimal("150")
+            reasons.append("blank description")
+        median_amount = account_medians.get(entry.account)
+        if median_amount and median_amount > 0 and amount > median_amount * Decimal("3"):
+            score += Decimal("250")
+            reasons.append("amount exceeds 3x historical median")
+        known_accounts = user_accounts.get(entry.user, set())
+        if known_accounts and entry.account not in known_accounts:
+            score += Decimal("200")
+            reasons.append("user unusual for account")
+        level = RiskLevel.CRITICAL if score >= 900 else RiskLevel.HIGH if score >= 600 else RiskLevel.MEDIUM if score >= 250 else RiskLevel.LOW
+        return JournalEntryScore(entry=entry, score=score, level=level, reasons=reasons, source_refs=list(entry.source_refs))
+
+
+def _coerce_entry(entry: JournalEntry | dict[str, Any]) -> JournalEntry:
+    if isinstance(entry, JournalEntry):
+        return entry
+    return JournalEntry(
+        id=str(entry["id"]),
+        account=str(entry.get("account", "")),
+        amount=entry.get("amount", 0),
+        entry_date=entry.get("entry_date") or entry.get("date"),
+        user=str(entry.get("user", "")),
+        description=str(entry.get("description", "")),
+        manual=bool(entry.get("manual", True)),
+        approved_by=entry.get("approved_by"),
+        posted_at=entry.get("posted_at"),
+        source_refs=list(entry.get("source_refs", [])),
+    )
+
+
+def _median_amount_by_account(entries: list[JournalEntry]) -> dict[str, Decimal]:
+    grouped: dict[str, list[Decimal]] = {}
+    for entry in entries:
+        grouped.setdefault(entry.account, []).append(abs(entry.amount))
+    return {account: decimalize(median(values)) for account, values in grouped.items() if values}
+
+
+def _accounts_by_user(entries: list[JournalEntry]) -> dict[str, set[str]]:
+    out: dict[str, set[str]] = {}
+    for entry in entries:
+        out.setdefault(entry.user, set()).add(entry.account)
+    return out
+
+
+def _is_round_amount(amount: Decimal) -> bool:
+    return amount != 0 and amount % Decimal("1000") == 0
+
+
+def _outside_business_hours(value: datetime) -> bool:
+    return value.weekday() >= 5 or value.time() < time(6, 0) or value.time() > time(20, 0)