Milestone 1: First Verified Analyst Answer (Gross Margin)

Author: aadityat23

finverify-terminal/CAPABILITIES.md

@@ -5,6 +5,7 @@
 | Scale          | ✅     | ✅    | ⏳    | ✅    | Stable |
 | Sign           | ✅     | ✅    | ⏳    | ✅    |       |
 | Magnitude      | ✅     | ✅    | ⏳    | ✅    |       |
+| Profitability: Gross Margin | ✅ | ✅ | ⏳ | ✅ | Milestone 1 |
 | Percentage     | ⏳     | ❌    | ❌    | ❌    | Planned |
 | Basis Points   | ⏳     | ❌    | ❌    | ❌    | Planned |
 | EPS            | ⏳     | ❌    | ❌    | ❌    | Planned |

finverify-terminal/backend/config/concepts.yaml

@@ -0,0 +1,43 @@
+{
+  "concepts": {
+    "Revenue": {
+      "aliases": ["Net Sales", "Turnover", "Sales"],
+      "xbrl_tags": [
+        "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax",
+        "us-gaap:RevenueFromContractWithCustomerIncludingAssessedTax",
+        "us-gaap:Revenues"
+      ],
+      "unit": "USD",
+      "statement": "IncomeStatement",
+      "period_rules": "FiscalYear",
+      "currency_rules": "USD",
+      "validation": "Must be > 0"
+    },
+    "CostOfGoodsSold": {
+      "aliases": ["COGS", "Cost of Sales", "Cost of Revenue"],
+      "xbrl_tags": [
+        "us-gaap:CostOfGoodsSold",
+        "us-gaap:CostOfGoodsAndServicesSold",
+        "us-gaap:CostOfSales"
+      ],
+      "unit": "USD",
+      "statement": "IncomeStatement",
+      "period_rules": "FiscalYear",
+      "currency_rules": "USD",
+      "validation": "Must be > 0"
+    },
+    "GrossProfit": {
+      "aliases": ["Gross Profit"],
+      "xbrl_tags": ["us-gaap:GrossProfit"],
+      "unit": "USD",
+      "statement": "IncomeStatement"
+    },
+    "GrossMargin": {
+      "aliases": ["Gross Profit Margin"],
+      "formula": "(Revenue - CostOfGoodsSold) / Revenue",
+      "unit": "percentage",
+      "statement": "IncomeStatement",
+      "requires": ["Revenue", "CostOfGoodsSold"]
+    }
+  }
+}

finverify-terminal/backend/core/financial/__init__.py

@@ -0,0 +1,30 @@
+"""Financial-document reasoning primitives for Milestone 1."""
+
+from .concepts import ConceptRegistry
+from .contract import EvidenceContract, EvidenceContractBuilder, EvidenceItem
+from .document import FinancialDocument, FinancialPeriod, FinancialStatement, FinancialStatementItem
+from .formula import FormulaEngine
+from .mapper import StatementMapper
+from .parser import TaskParser
+from .planner import ExecutionPlanner
+from .reasoning import ReasoningEngine
+from .tasks import FinancialTask, TaskRegistry, TaskType
+
+__all__ = [
+    "ConceptRegistry",
+    "EvidenceContract",
+    "EvidenceContractBuilder",
+    "EvidenceItem",
+    "ExecutionPlanner",
+    "FinancialDocument",
+    "FinancialPeriod",
+    "FinancialStatement",
+    "FinancialStatementItem",
+    "FinancialTask",
+    "FormulaEngine",
+    "ReasoningEngine",
+    "StatementMapper",
+    "TaskParser",
+    "TaskRegistry",
+    "TaskType",
+]

finverify-terminal/backend/core/financial/concepts.py

@@ -0,0 +1,43 @@
+"""Concept registry loader for financial reasoning."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml
+except ImportError:
+    yaml = None
+
+
+class ConceptRegistry:
+    def __init__(self, config_path: str | Path):
+        with open(config_path, encoding="utf-8") as handle:
+            if yaml is not None:
+                data = yaml.safe_load(handle) or {}
+            else:
+                data = json.load(handle)
+        self.concepts: dict[str, dict[str, Any]] = data.get("concepts", {})
+        self._build_indexes()
+
+    def _build_indexes(self) -> None:
+        self.alias_map: dict[str, str] = {}
+        self.tag_map: dict[str, str] = {}
+        for name, spec in self.concepts.items():
+            self.alias_map[name.lower()] = name
+            for alias in spec.get("aliases", []):
+                self.alias_map[alias.lower()] = name
+            for tag in spec.get("xbrl_tags", []):
+                normalized_tag = tag.lower()
+                self.tag_map[normalized_tag] = name
+                if ":" in normalized_tag:
+                    self.tag_map[normalized_tag.split(":", 1)[1]] = name
+
+    def get_concept(self, name: str) -> dict[str, Any]:
+        return self.concepts.get(name, {})
+
+    def resolve_alias(self, alias: str) -> str | None:
+        return self.alias_map.get(alias.lower())
+
+    def resolve_xbrl_tag(self, tag: str) -> str | None:
+        return self.tag_map.get(tag.lower())

finverify-terminal/backend/core/financial/contract.py

@@ -0,0 +1,53 @@
+"""Evidence contracts for financial reasoning tasks."""
+
+from pydantic import BaseModel, Field
+
+from .document import FinancialDocument
+
+
+class EvidenceItem(BaseModel):
+    concept: str
+    value: float
+    unit: str
+    statement: str
+    source_ref: str
+    xbrl_tag: str | None = None
+
+
+class EvidenceContract(BaseModel):
+    required: list[str]
+    provided: list[EvidenceItem]
+    missing: list[str]
+    optional: list[EvidenceItem] = Field(default_factory=list)
+
+
+class EvidenceContractBuilder:
+    @staticmethod
+    def build(document: FinancialDocument, required_concepts: list[str]) -> EvidenceContract:
+        items_by_concept: dict[str, EvidenceItem] = {}
+        optional: list[EvidenceItem] = []
+
+        for statement in document.statements.values():
+            for item in statement.items:
+                evidence_item = EvidenceItem(
+                    concept=item.concept,
+                    value=item.value,
+                    unit=item.unit,
+                    statement=statement.name,
+                    source_ref=item.source_ref,
+                    xbrl_tag=item.xbrl_tag,
+                )
+                if item.concept in required_concepts and item.concept not in items_by_concept:
+                    items_by_concept[item.concept] = evidence_item
+                elif item.concept not in required_concepts:
+                    optional.append(evidence_item)
+
+        provided = [items_by_concept[concept] for concept in required_concepts if concept in items_by_concept]
+        missing = [concept for concept in required_concepts if concept not in items_by_concept]
+
+        return EvidenceContract(
+            required=required_concepts,
+            provided=provided,
+            missing=missing,
+            optional=optional,
+        )

finverify-terminal/backend/core/financial/document.py

@@ -0,0 +1,43 @@
+"""Canonical financial document models."""
+
+from datetime import date
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class FinancialPeriod(BaseModel):
+    start_date: date
+    end_date: date
+    fiscal_year: int
+    fiscal_quarter: Optional[int] = None
+
+
+class FinancialStatementItem(BaseModel):
+    concept: str
+    value: float
+    unit: str
+    period: FinancialPeriod
+    source_ref: str
+    xbrl_tag: Optional[str] = None
+    confidence: float = 1.0
+
+
+class FinancialStatement(BaseModel):
+    name: str
+    items: list[FinancialStatementItem] = Field(default_factory=list)
+    period: FinancialPeriod
+    currency: str = "USD"
+
+
+class FinancialDocument(BaseModel):
+    company_name: str
+    ticker: Optional[str] = None
+    cik: Optional[str] = None
+    filing_type: str
+    filing_date: date
+    periods: list[FinancialPeriod] = Field(default_factory=list)
+    statements: dict[str, FinancialStatement] = Field(default_factory=dict)
+    footnotes: dict[str, str] = Field(default_factory=dict)
+    metadata: dict[str, str] = Field(default_factory=dict)
+    source_url: Optional[str] = None

finverify-terminal/backend/core/financial/formula.py

@@ -0,0 +1,50 @@
+"""Deterministic arithmetic formula evaluation without eval()."""
+
+import ast
+import operator
+from typing import Mapping
+
+
+class FormulaEngine:
+    """Safe arithmetic evaluator backed by Python's AST."""
+
+    _binary_operators = {
+        ast.Add: operator.add,
+        ast.Sub: operator.sub,
+        ast.Mult: operator.mul,
+        ast.Div: operator.truediv,
+    }
+    _unary_operators = {
+        ast.UAdd: operator.pos,
+        ast.USub: operator.neg,
+    }
+
+    def evaluate(self, formula: str, values: Mapping[str, float]) -> float:
+        parsed = ast.parse(formula, mode="eval")
+        return float(self._evaluate_node(parsed.body, values))
+
+    def _evaluate_node(self, node: ast.AST, values: Mapping[str, float]) -> float:
+        if isinstance(node, ast.BinOp):
+            return self._evaluate_binary(node, values)
+        if isinstance(node, ast.UnaryOp) and type(node.op) in self._unary_operators:
+            operand = self._evaluate_node(node.operand, values)
+            return self._unary_operators[type(node.op)](operand)
+        if isinstance(node, ast.Name):
+            if node.id not in values:
+                raise KeyError(f"Missing value for concept '{node.id}'")
+            return float(values[node.id])
+        if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
+            return float(node.value)
+        if isinstance(node, ast.Num):
+            return float(node.n)
+        raise ValueError(f"Unsupported formula node: {ast.dump(node)}")
+
+    def _evaluate_binary(self, node: ast.BinOp, values: Mapping[str, float]) -> float:
+        operator_type = type(node.op)
+        if operator_type not in self._binary_operators:
+            raise ValueError(f"Unsupported operator: {operator_type.__name__}")
+        left = self._evaluate_node(node.left, values)
+        right = self._evaluate_node(node.right, values)
+        if operator_type is ast.Div and right == 0:
+            raise ZeroDivisionError("Division by zero in formula evaluation")
+        return self._binary_operators[operator_type](left, right)