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

algo_cli/intelligence/finance/close.py

@@ -0,0 +1,332 @@
+"""B88/B97/B98. Close DAG, variance miner, accrual/reversal engine."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date
+from decimal import Decimal
+from typing import Any, Iterable
+
+from .common import FinanceException, ReviewGate, Severity, SourceRef, decimalize, stable_exception_id
+from .exceptions import ControllerExceptionQueue
+
+
+@dataclass(frozen=True)
+class CloseTask:
+    id: str
+    name: str
+    duration_hours: Decimal | int | str = Decimal("1")
+    dependencies: set[str] = field(default_factory=set)
+    owner: str | None = None
+    due_day: int | None = None
+    completed: bool = False
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "duration_hours", decimalize(self.duration_hours))
+        object.__setattr__(self, "dependencies", set(self.dependencies))
+
+
+@dataclass(frozen=True)
+class BlockedTask:
+    task: CloseTask
+    missing_dependencies: set[str]
+
+
+class CloseDAG:
+    """Month-end close task DAG with ready/blocked/critical-path analysis."""
+
+    def __init__(self) -> None:
+        self.tasks: dict[str, CloseTask] = {}
+
+    def add_task(self, task: CloseTask) -> None:
+        self.tasks[task.id] = task
+
+    def ready_tasks(self, completed: set[str] | None = None) -> list[CloseTask]:
+        completed = set(completed or ()) | {task.id for task in self.tasks.values() if task.completed}
+        return sorted(
+            [
+                task for task in self.tasks.values()
+                if task.id not in completed and task.dependencies <= completed
+            ],
+            key=lambda task: (task.due_day if task.due_day is not None else 99, task.id),
+        )
+
+    def blocked_tasks(self, completed: set[str] | None = None) -> list[BlockedTask]:
+        completed = set(completed or ()) | {task.id for task in self.tasks.values() if task.completed}
+        blocked: list[BlockedTask] = []
+        for task in self.tasks.values():
+            missing = task.dependencies - completed
+            if task.id not in completed and missing:
+                blocked.append(BlockedTask(task=task, missing_dependencies=missing))
+        return sorted(blocked, key=lambda row: row.task.id)
+
+    def topological_order(self) -> list[str]:
+        indegree = {task_id: 0 for task_id in self.tasks}
+        children: dict[str, list[str]] = {task_id: [] for task_id in self.tasks}
+        for task in self.tasks.values():
+            for dep in task.dependencies:
+                if dep not in self.tasks:
+                    raise ValueError(f"Unknown dependency {dep!r} for close task {task.id!r}")
+                indegree[task.id] += 1
+                children[dep].append(task.id)
+        ready = sorted([task_id for task_id, degree in indegree.items() if degree == 0])
+        order: list[str] = []
+        while ready:
+            current = ready.pop(0)
+            order.append(current)
+            for child in sorted(children[current]):
+                indegree[child] -= 1
+                if indegree[child] == 0:
+                    ready.append(child)
+                    ready.sort()
+        if len(order) != len(self.tasks):
+            raise ValueError("Close DAG contains a cycle")
+        return order
+
+    def critical_path(self) -> list[CloseTask]:
+        order = self.topological_order()
+        distance: dict[str, Decimal] = {}
+        predecessor: dict[str, str | None] = {}
+        for task_id in order:
+            task = self.tasks[task_id]
+            best_dep = None
+            best_distance = Decimal("0")
+            for dep in task.dependencies:
+                if distance[dep] > best_distance:
+                    best_dep = dep
+                    best_distance = distance[dep]
+            distance[task_id] = best_distance + task.duration_hours
+            predecessor[task_id] = best_dep
+        if not distance:
+            return []
+        end = max(distance, key=lambda task_id: (distance[task_id], task_id))
+        path_ids: list[str] = []
+        while end is not None:
+            path_ids.append(end)
+            end = predecessor[end]
+        path_ids.reverse()
+        return [self.tasks[task_id] for task_id in path_ids]
+
+
+@dataclass(frozen=True)
+class AccrualPolicy:
+    id: str = "default-accrual"
+    minimum_amount: Decimal = Decimal("100")
+    require_reversal_date: bool = True
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "minimum_amount", decimalize(self.minimum_amount))
+
+
+@dataclass(frozen=True)
+class AccrualProposal:
+    id: str
+    vendor: str
+    amount: Decimal
+    basis: str
+    reversal_date: date | None
+    source_refs: list[SourceRef]
+    review_gate: ReviewGate = ReviewGate.CONTROLLER_REVIEW
+
+
+@dataclass(frozen=True)
+class ReversalProposal:
+    id: str
+    accrual_id: str
+    amount: Decimal
+    reversal_date: date
+    source_refs: list[SourceRef]
+
+
+class AccrualEngine:
+    """Propose accruals and reversals; never posts journal entries."""
+
+    def propose_accruals(
+        self,
+        expenses: Iterable[dict[str, Any]],
+        receipts: Iterable[dict[str, Any]],
+        invoices: Iterable[dict[str, Any]],
+        policy: AccrualPolicy | None = None,
+    ) -> list[AccrualProposal]:
+        policy = policy or AccrualPolicy()
+        invoiced_keys = {_accrual_key(row) for row in invoices}
+        proposals: list[AccrualProposal] = []
+        for row in list(expenses) + list(receipts):
+            amount = abs(decimalize(row.get("amount", 0)))
+            if amount < policy.minimum_amount:
+                continue
+            key = _accrual_key(row)
+            if key in invoiced_keys:
+                continue
+            reversal_date = row.get("reversal_date")
+            if isinstance(reversal_date, str):
+                reversal_date = date.fromisoformat(reversal_date[:10])
+            source_refs = list(row.get("source_refs", []))
+            if not row.get("basis") or (policy.require_reversal_date and reversal_date is None) or not source_refs:
+                continue
+            proposal_id = stable_exception_id("B98", [key, amount, reversal_date])
+            proposals.append(AccrualProposal(
+                id=proposal_id,
+                vendor=str(row.get("vendor", "")),
+                amount=amount,
+                basis=str(row.get("basis")),
+                reversal_date=reversal_date,
+                source_refs=source_refs,
+            ))
+        return proposals
+
+    def propose_reversals(self, prior_accruals: Iterable[AccrualProposal], current_period: str) -> list[ReversalProposal]:
+        reversals: list[ReversalProposal] = []
+        for accrual in prior_accruals:
+            if not accrual.reversal_date:
+                continue
+            if f"{accrual.reversal_date.year:04d}-{accrual.reversal_date.month:02d}" == current_period:
+                reversals.append(ReversalProposal(
+                    id=stable_exception_id("B98R", [accrual.id, current_period]),
+                    accrual_id=accrual.id,
+                    amount=-accrual.amount,
+                    reversal_date=accrual.reversal_date,
+                    source_refs=list(accrual.source_refs),
+                ))
+        return reversals
+
+
+@dataclass(frozen=True)
+class Variance:
+    account: str
+    current: Decimal
+    comparison: Decimal
+    difference: Decimal
+    percent_change: Decimal | None
+    source_refs: list[SourceRef] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class VarianceExplanation:
+    variance: Variance
+    driver: str | None
+    explanation: str
+    supported: bool
+    source_refs: list[SourceRef]
+    review_gate: ReviewGate = ReviewGate.CONTROLLER_REVIEW
+
+
+class VarianceExplanationMiner:
+    """Detect and explain material flux without accepting tautologies."""
+
+    def detect_variances(
+        self,
+        current: dict[str, Any],
+        prior: dict[str, Any],
+        budget: dict[str, Any] | None = None,
+        materiality: Any = Decimal("1000"),
+    ) -> list[Variance]:
+        baseline = budget or prior
+        threshold = abs(decimalize(materiality))
+        variances: list[Variance] = []
+        for account, current_value in current.items():
+            current_amount = decimalize(current_value)
+            comparison = decimalize(baseline.get(account, 0))
+            difference = current_amount - comparison
+            if abs(difference) < threshold:
+                continue
+            percent = None if comparison == 0 else difference / abs(comparison)
+            variances.append(Variance(
+                account=account,
+                current=current_amount,
+                comparison=comparison,
+                difference=difference,
+                percent_change=percent,
+            ))
+        return sorted(variances, key=lambda row: (abs(row.difference), row.account), reverse=True)
+
+    def explain(self, variance: Variance, activity_sources: Iterable[dict[str, Any]]) -> VarianceExplanation:
+        allowed = {
+            "volume",
+            "price",
+            "rate",
+            "mix",
+            "timing",
+            "correction",
+            "new-vendor",
+            "new-customer",
+            "job-status",
+            "headcount",
+            "tax-rate",
+            "accrual",
+            "reversal",
+            "reclass",
+        }
+        for source in activity_sources:
+            if str(source.get("account", "")).lower() != variance.account.lower():
+                continue
+            driver = str(source.get("driver", "")).lower()
+            explanation = str(source.get("explanation", "")).strip()
+            source_refs = list(source.get("source_refs", []))
+            if driver in allowed and source_refs and not _is_tautology(variance.account, explanation):
+                return VarianceExplanation(
+                    variance=variance,
+                    driver=driver,
+                    explanation=explanation,
+                    supported=True,
+                    source_refs=source_refs,
+                    review_gate=ReviewGate.DRAFT,
+                )
+        return VarianceExplanation(
+            variance=variance,
+            driver=None,
+            explanation="driver unclear — flag for controller",
+            supported=False,
+            source_refs=[],
+        )
+
+
+@dataclass
+class ClosePackageInputs:
+    current_balances: dict[str, Any] = field(default_factory=dict)
+    prior_balances: dict[str, Any] = field(default_factory=dict)
+    activity_sources: list[dict[str, Any]] = field(default_factory=list)
+    materiality: Decimal = Decimal("1000")
+
+
+@dataclass
+class ClosePackageResult:
+    variances: list[Variance]
+    explanations: list[VarianceExplanation]
+    exception_queue: ControllerExceptionQueue
+    review_gate: ReviewGate = ReviewGate.CONTROLLER_REVIEW
+
+
+class ClosePackageAnalyzer:
+    """Compose close analysis and route issues to a controller queue."""
+
+    def run(self, inputs: ClosePackageInputs) -> ClosePackageResult:
+        miner = VarianceExplanationMiner()
+        variances = miner.detect_variances(inputs.current_balances, inputs.prior_balances, materiality=inputs.materiality)
+        explanations = [miner.explain(variance, inputs.activity_sources) for variance in variances]
+        queue = ControllerExceptionQueue()
+        for explanation in explanations:
+            if not explanation.supported:
+                queue.add(FinanceException(
+                    id=stable_exception_id("B97", [explanation.variance.account, explanation.variance.difference]),
+                    pattern_id="B97",
+                    severity=Severity.MEDIUM,
+                    amount=abs(explanation.variance.difference),
+                    message=f"Unsupported variance explanation for {explanation.variance.account}",
+                    source_refs=list(explanation.variance.source_refs),
+                    tags={"variance", f"account:{explanation.variance.account.lower()}"},
+                ))
+        return ClosePackageResult(variances=variances, explanations=explanations, exception_queue=queue)
+
+
+def _accrual_key(row: dict[str, Any]) -> tuple[str, str, str]:
+    return (str(row.get("vendor", "")).lower(), str(row.get("description", "")).lower(), str(row.get("period", "")))
+
+
+def _is_tautology(account: str, explanation: str) -> bool:
+    low = explanation.lower()
+    if not low:
+        return True
+    tokens = [token for token in account.lower().replace("-", " ").split() if len(token) > 3]
+    tautology_phrases = ("increased due to higher", "decreased due to lower", "changed due to change")
+    return any(phrase in low for phrase in tautology_phrases) or (tokens and all(token in low for token in tokens) and len(low.split()) < 8)

algo_cli/intelligence/finance/common.py

@@ -0,0 +1,244 @@
+"""Shared finance/controller data contracts.
+
+These primitives back Track C patterns B87-B105.  They are deliberately
+local-only and deterministic: engines produce draft analysis, provenance, and
+review gates; they never post JEs, approve payments, file taxes, or distribute
+external work product.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from decimal import Decimal, InvalidOperation
+from enum import Enum, IntEnum
+import hashlib
+import json
+import re
+from typing import Any, Iterable
+
+
+class Severity(IntEnum):
+    INFO = 0
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+    CRITICAL = 4
+
+
+class RiskLevel(IntEnum):
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+    CRITICAL = 4
+
+
+class EvidenceStatus(Enum):
+    OPEN = "open"
+    REQUESTED = "requested"
+    RECEIVED = "received"
+    REVIEWED = "reviewed"
+    STALE = "stale"
+    WAIVED = "waived"
+
+
+class ReviewGate(Enum):
+    DRAFT = "draft"
+    CONTROLLER_REVIEW = "controller_review"
+    CPA_REVIEW = "cpa_review"
+    EXTERNAL_APPROVAL_REQUIRED = "external_approval_required"
+
+
+@dataclass(frozen=True)
+class Money:
+    amount: Decimal
+    currency: str = "USD"
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "amount", decimalize(self.amount))
+        object.__setattr__(self, "currency", self.currency.upper())
+
+
+@dataclass(frozen=True)
+class SourceRef:
+    source_id: str
+    path: str | None = None
+    row: int | None = None
+    column: str | None = None
+    document_hash: str | None = None
+    note: str | None = None
+
+
+@dataclass
+class EvidenceItem:
+    id: str
+    description: str
+    source_refs: list[SourceRef] = field(default_factory=list)
+    prepared_by: str | None = None
+    reviewed_by: str | None = None
+    status: EvidenceStatus = EvidenceStatus.OPEN
+
+    @property
+    def has_support(self) -> bool:
+        return bool(self.source_refs)
+
+
+@dataclass
+class FinanceException:
+    id: str
+    pattern_id: str
+    severity: Severity
+    amount: Decimal | None
+    message: str
+    source_refs: list[SourceRef] = field(default_factory=list)
+    owner: str | None = None
+    due_date: date | None = None
+    tags: set[str] = field(default_factory=set)
+    requires_human_review: bool = True
+    review_gate: ReviewGate = ReviewGate.CONTROLLER_REVIEW
+    tolerance_used: Decimal | None = None
+    materiality_policy_id: str | None = None
+    waived: bool = False
+    waiver_rationale: str | None = None
+    waiver_approver: str | None = None
+    waiver_expires: date | None = None
+
+    def __post_init__(self) -> None:
+        if self.amount is not None:
+            self.amount = decimalize(self.amount)
+        if not isinstance(self.severity, Severity):
+            self.severity = Severity[self.severity]
+        self.tags = {str(tag).lower() for tag in self.tags}
+
+
+@dataclass
+class MaterialityPolicy:
+    """Small deterministic scoring policy for controller exception queues."""
+
+    id: str = "default"
+    quantitative_threshold: Decimal = Decimal("1000")
+    qualitative_tags: set[str] = field(default_factory=lambda: {
+        "fraud",
+        "sod",
+        "segregation-of-duties",
+        "tax",
+        "covenant",
+        "related-party",
+        "external-reporting",
+        "executive-override",
+    })
+    severity_weight: Decimal = Decimal("1000")
+    qualitative_weight: Decimal = Decimal("10000")
+    deadline_weight: Decimal = Decimal("100")
+    recurrence_weight: Decimal = Decimal("250")
+
+    def __post_init__(self) -> None:
+        self.quantitative_threshold = decimalize(self.quantitative_threshold)
+        self.qualitative_tags = {tag.lower() for tag in self.qualitative_tags}
+
+    def quantitative_score(self, amount: Decimal | int | float | str | None) -> Decimal:
+        if amount is None:
+            return Decimal("0")
+        absolute = abs(decimalize(amount))
+        if self.quantitative_threshold <= 0:
+            return absolute
+        return min(absolute / self.quantitative_threshold, Decimal("10")) * Decimal("100")
+
+    def qualitative_score(self, tags: Iterable[str]) -> Decimal:
+        normalized = {str(tag).lower() for tag in tags}
+        hits = normalized & self.qualitative_tags
+        return self.qualitative_weight * len(hits)
+
+    def score_exception(self, exception: FinanceException, as_of: date | None = None) -> Decimal:
+        score = Decimal(int(exception.severity)) * self.severity_weight
+        score += self.quantitative_score(exception.amount)
+        score += self.qualitative_score(exception.tags)
+        recurrence = _tag_int(exception.tags, "recurrence:")
+        score += Decimal(recurrence) * self.recurrence_weight
+        if exception.due_date and as_of:
+            days = (exception.due_date - as_of).days
+            if days <= 0:
+                score += self.deadline_weight * Decimal("10")
+            elif days <= 5:
+                score += self.deadline_weight * Decimal(6 - days)
+        return score
+
+
+def decimalize(value: Decimal | int | float | str | None) -> Decimal:
+    """Convert common finance values to Decimal without binary-float surprises."""
+    if value is None:
+        return Decimal("0")
+    if isinstance(value, Decimal):
+        return value
+    if isinstance(value, bool):
+        return Decimal(int(value))
+    text = str(value).strip()
+    if not text:
+        return Decimal("0")
+    negative = text.startswith("(") and text.endswith(")")
+    text = text.strip("()")
+    text = text.replace("$", "").replace(",", "").replace("%", "")
+    try:
+        amount = Decimal(text)
+    except InvalidOperation as exc:
+        raise ValueError(f"Cannot convert to Decimal: {value!r}") from exc
+    return -amount if negative else amount
+
+
+def within_tolerance(left: Any, right: Any, tolerance: Any = Decimal("0")) -> bool:
+    return abs(decimalize(left) - decimalize(right)) <= abs(decimalize(tolerance))
+
+
+def stable_exception_id(pattern_id: str, key_fields: Iterable[Any]) -> str:
+    payload = json.dumps([pattern_id, list(key_fields)], sort_keys=True, default=str)
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:16]
+
+
+def hash_source_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+_VENDOR_SUFFIXES = {
+    "inc",
+    "incorporated",
+    "llc",
+    "l.l.c",
+    "ltd",
+    "co",
+    "company",
+    "corp",
+    "corporation",
+}
+
+
+def normalize_vendor_name(name: str | None) -> str:
+    text = (name or "").lower()
+    text = re.sub(r"[^a-z0-9\s]", " ", text)
+    words = [word for word in text.split() if word not in _VENDOR_SUFFIXES]
+    return " ".join(words)
+
+
+def normalize_invoice_number(number: str | int | None) -> str:
+    text = str(number or "").upper().strip()
+    text = re.sub(r"[^A-Z0-9]", "", text)
+    # Keep a fully-zero number as "0", but remove padding for common invoice keys.
+    stripped = text.lstrip("0")
+    return stripped or ("0" if text else "")
+
+
+def month_bucket(value: date | datetime | str) -> str:
+    if isinstance(value, datetime):
+        value = value.date()
+    elif isinstance(value, str):
+        value = datetime.fromisoformat(value[:10]).date()
+    return f"{value.year:04d}-{value.month:02d}"
+
+
+def _tag_int(tags: Iterable[str], prefix: str) -> int:
+    for tag in tags:
+        if tag.startswith(prefix):
+            try:
+                return int(tag.split(":", 1)[1])
+            except (IndexError, ValueError):
+                return 0
+    return 0