Add Phase 6 self improving ledger selection engine

2026-08-22 13:30:38 +05:30
parent ba0d638dfb
commit 7e1b9c24ef
7 changed files with 1096 additions and 0 deletions
@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from sqlalchemy import Boolean, DateTime, Float, ForeignKey, Integer, String, Text, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.core.db.common import CommonBase
+
+
+class AccountingLedgerLearningRule(CommonBase):
+    """Client-scoped learned evidence used to rank accounting natures.
+
+    Rules are intentionally contextual.  A supplier rule learned for one client
+    never becomes a universal rule for another client.
+    """
+
+    __tablename__ = "accounting_ledger_learning_rules"
+    __table_args__ = (
+        UniqueConstraint(
+            "tenant_id", "client_id", "tally_guid", "rule_type", "rule_key", "nature_id", "ledger_name",
+            name="uq_accounting_ledger_learning_rule",
+        ),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    tenant_id: Mapped[int] = mapped_column(ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False, index=True)
+    client_id: Mapped[int] = mapped_column(ForeignKey("clients.id", ondelete="CASCADE"), nullable=False, index=True)
+    tally_guid: Mapped[str] = mapped_column(String(120), nullable=False, default="", index=True)
+
+    rule_type: Mapped[str] = mapped_column(String(40), nullable=False, index=True)
+    rule_key: Mapped[str] = mapped_column(String(500), nullable=False, index=True)
+    display_value: Mapped[str] = mapped_column(String(500), nullable=False, default="")
+
+    nature_id: Mapped[int] = mapped_column(ForeignKey("accounting_natures.id", ondelete="RESTRICT"), nullable=False, index=True)
+    ledger_name: Mapped[str] = mapped_column(String(240), nullable=False, default="")
+
+    confirmation_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    rejection_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    confidence_percent: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True, index=True)
+
+    last_confirmed_by_user_id: Mapped[int | None] = mapped_column(ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    last_confirmed_at_utc: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    created_at_utc: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False)
+    updated_at_utc: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+        nullable=False,
+    )
+
+
+class AccountingLedgerLearningEvent(CommonBase):
+    """Immutable review feedback used to audit and improve ledger selection."""
+
+    __tablename__ = "accounting_ledger_learning_events"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    tenant_id: Mapped[int] = mapped_column(ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False, index=True)
+    client_id: Mapped[int] = mapped_column(ForeignKey("clients.id", ondelete="CASCADE"), nullable=False, index=True)
+    tally_guid: Mapped[str] = mapped_column(String(120), nullable=False, default="", index=True)
+
+    source_type: Mapped[str] = mapped_column(String(40), nullable=False, default="manual_review", index=True)
+    supplier_name: Mapped[str] = mapped_column(String(240), nullable=False, default="", index=True)
+    supplier_gstin: Mapped[str] = mapped_column(String(20), nullable=False, default="", index=True)
+    hsn_code: Mapped[str] = mapped_column(String(20), nullable=False, default="", index=True)
+    description_text: Mapped[str | None] = mapped_column(Text, nullable=True)
+    amount: Mapped[float | None] = mapped_column(Float, nullable=True)
+
+    suggested_nature_id: Mapped[int | None] = mapped_column(ForeignKey("accounting_natures.id", ondelete="SET NULL"), nullable=True, index=True)
+    suggested_ledger_name: Mapped[str] = mapped_column(String(240), nullable=False, default="")
+    suggested_confidence: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+
+    final_nature_id: Mapped[int] = mapped_column(ForeignKey("accounting_natures.id", ondelete="RESTRICT"), nullable=False, index=True)
+    final_ledger_name: Mapped[str] = mapped_column(String(240), nullable=False, default="")
+    accepted_suggestion: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False, index=True)
+
+    explanation_json: Mapped[str | None] = mapped_column(Text, nullable=True)
+    business_profile_snapshot_json: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    reviewed_by_user_id: Mapped[int | None] = mapped_column(ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    created_at_utc: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False, index=True)