specsmith 0.2.4.dev54__py3-none-any.whl → 0.2.4.dev589__py3-none-any.whl

epistemic/__init__.py

@@ -0,0 +1,174 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Layer1Labs Silicon, Inc. All rights reserved.
+"""Applied Epistemic Engineering — standalone Python library.
+
+Install
+-------
+    pip install specsmith        # installs both specsmith and epistemic
+
+The ``epistemic`` package is co-installed with specsmith and has **zero
+external dependencies** beyond Python 3.10+. It can be imported by any
+Python project to incorporate AEE practices.
+
+Quick start
+-----------
+The simplest entry point is ``AEESession``::
+
+    from epistemic import AEESession
+
+    session = AEESession(project_name="my-research")
+    session.add_belief(
+        artifact_id="HYP-001",
+        propositions=["Our decipherment hypothesis is internally consistent"],
+        epistemic_boundary=["Corpus: 500 inscriptions, phase 1 only"],
+        domain="linguistics",
+    )
+    result = session.run()
+    print(result.summary())
+
+For non-trivial projects you'll want to:
+
+1. ``add_belief()`` — register claims, hypotheses, requirements
+2. ``add_evidence()`` / ``mark_covered()`` — record what's been validated
+3. ``accept()`` — elevate to ACCEPTED status (binds stress-testing)
+4. ``run()`` — execute the full AEE pipeline
+5. ``seal()`` — cryptographically seal the epistemic state
+
+What AEE provides
+-----------------
+Applied Epistemic Engineering treats belief systems like code: codable,
+testable, and deployable. Its formal mathematical foundations include:
+
+**Five axioms:**
+  1. Observability      — every belief must be inspectable (hidden assumptions → stop)
+  2. Falsifiability     — every belief must be challengeable (dogma ≠ engineering)
+  3. Irreducibility     — decompose to atomic primitives (compound claims → Logic Knots)
+  4. Reconstructability — every failed belief can be reconstructed (scope may narrow)
+  5. Convergence        — S+R iteration always converges to equilibrium E
+
+**Core process: Frame → Disassemble → Stress-Test → Reconstruct**
+
+**Key operators:**
+  S(B) = StressTester — adversarial challenge function
+  R(K) = RecoveryOperator — resolves Logic Knots K
+  G     = FailureModeGraph — maps stress-test → breakpoint relations
+  E     = Equilibrium point where S(G) yields no new failures
+  C     = Certainty score ∈ [0, 1] from CertaintyEngine
+
+Real-world use cases
+--------------------
+  Software engineering:  requirements as BeliefArtifacts, tests as falsifiers
+  Linguistics research:  hypotheses as BeliefArtifacts, experiments as evidence
+  AI alignment:          model assumptions as BeliefArtifacts, red-teaming as stress-tests
+  Policy/compliance:     regulations as BeliefArtifacts, audits as failure modes
+  Patent prosecution:    claims as BeliefArtifacts, prior art as stress-tests
+
+glossa-lab example
+------------------
+    from epistemic import AEESession, ConfidenceLevel, BeliefStatus
+    from pathlib import Path
+
+    # Create a session for Indus script decipherment research
+    session = AEESession(
+        project_name="glossa-lab-indus",
+        threshold=0.65,
+        state_file=Path(".epistemic/indus.json"),
+        trace_dir=Path(".epistemic"),
+    )
+
+    # Load previous session state
+    session.load()
+
+    # Register competing hypotheses
+    session.add_belief(
+        artifact_id="HYP-IND-001",
+        propositions=["The Indus script is logosyllabic"],
+        epistemic_boundary=["Mahadevan corpus, 2977 inscriptions, 1977 edition"],
+        domain="epigraphy",
+        status=BeliefStatus.ACCEPTED,
+        confidence=ConfidenceLevel.LOW,
+    )
+    session.add_belief(
+        artifact_id="HYP-IND-002",
+        propositions=["Indus sign frequency follows Zipf distribution"],
+        epistemic_boundary=["Same corpus as HYP-IND-001"],
+        inferential_links=["HYP-IND-001"],  # confidence propagates from HYP-IND-001
+        domain="epigraphy",
+        status=BeliefStatus.ACCEPTED,
+    )
+
+    # Record experimental evidence
+    session.add_evidence("HYP-IND-001", "Rao et al. 2009 — conditional entropy study")
+    session.add_evidence("HYP-IND-002", "Mahadevan 1977 — sign frequency tables")
+    session.mark_covered("HYP-IND-001")  # has experimental coverage
+
+    # Run the full AEE pipeline
+    result = session.run()
+    print(result.summary())
+
+    # If there are Logic Knots (competing theories), inspect them:
+    for id1, id2, reason in result.stress_result.logic_knots:
+        print(f"Conflict: {id1} vs {id2}: {reason}")
+
+    # See the certainty map by domain
+    for score in result.certainty_report.scores:
+        print(f"  {score.artifact_id}: {score.propagated_score:.2f} [{score.label}]")
+
+    # Seal this session's epistemic state
+    session.seal("stress-test", "Indus decipherment hypothesis stress-test v2")
+    session.save()
+
+References
+----------
+- AEE:    https://appliedepistemicengineering.com/
+- ARE:    https://github.com/organvm-i-theoria/auto-revision-epistemic-engine
+- VERITAS: https://github.com/AionSystem/VERITAS
+- Springer: https://doi.org/10.1007/s11948-023-00451-3
+"""
+
+from __future__ import annotations
+
+from epistemic.belief import (
+    BeliefArtifact,
+    BeliefStatus,
+    ConfidenceLevel,
+    FailureMode,
+    FailureSeverity,
+    beliefs_from_dicts,
+    parse_requirements_as_beliefs,
+)
+from epistemic.certainty import ArtifactCertainty, CertaintyEngine, CertaintyReport
+from epistemic.failure_graph import FailureModeGraph, GraphNode
+from epistemic.recovery import RecoveryOperator, RecoveryProposal, RecoveryStrategy
+from epistemic.session import AEEResult, AEESession
+from epistemic.stress_tester import StressTester, StressTestResult
+
+__version__ = "0.3.0"
+
+__all__ = [
+    # Session facade (primary entry point)
+    "AEESession",
+    "AEEResult",
+    # Belief model
+    "BeliefArtifact",
+    "BeliefStatus",
+    "ConfidenceLevel",
+    "FailureMode",
+    "FailureSeverity",
+    "parse_requirements_as_beliefs",
+    "beliefs_from_dicts",
+    # Stress testing
+    "StressTester",
+    "StressTestResult",
+    # Failure graph
+    "FailureModeGraph",
+    "GraphNode",
+    # Recovery
+    "RecoveryOperator",
+    "RecoveryProposal",
+    "RecoveryStrategy",
+    # Certainty
+    "CertaintyEngine",
+    "CertaintyReport",
+    "ArtifactCertainty",
+]

epistemic/belief.py

@@ -0,0 +1,364 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Layer1Labs Silicon, Inc. All rights reserved.
+"""Belief Artifact model — core AEE primitive.
+
+This module is part of the standalone ``epistemic`` library and has
+**zero dependencies outside Python's stdlib**. It can be imported by any
+Python 3.10+ project, independent of specsmith.
+
+    pip install specsmith       # installs both specsmith and epistemic
+    from epistemic import BeliefArtifact, StressTester, CertaintyEngine
+
+Applied Epistemic Engineering (AEE) treats belief systems like code:
+codable, testable, and deployable. A BeliefArtifact is the fundamental
+unit — a structured claim about what a system does, should do, or must not
+do, with an explicit epistemic boundary (the assumptions within which it holds)
+and a confidence level.
+
+Five foundational AEE axioms
+-----------------------------
+1. Observability      — Every belief must be inspectable. Hidden assumptions
+                        are a stop condition.
+2. Falsifiability     — Every belief must be challengeable. Unchallenged claims
+                        are dogma, not engineering.
+3. Irreducibility     — Decompose beliefs to atomic primitives. Compound claims
+                        often hide Logic Knots.
+4. Reconstructability — Every failed belief can be reconstructed. Recovery is
+                        always possible; scope may need to narrow.
+5. Convergence        — Systematic S+R application always converges to an
+                        Equilibrium Point E where S(G) yields no new failures.
+
+Real-world applications
+-----------------------
+- **Software engineering**: Requirements as BeliefArtifacts, test gaps as
+  stress-test failures, conflicting specs as Logic Knots.
+- **Research**: Hypotheses as BeliefArtifacts, experimental results as
+  evidence, competing theories as Logic Knots.
+- **AI alignment**: Model assumptions as BeliefArtifacts, red-teaming as
+  stress-testing, hallucinations as confidence failures.
+- **Policy / compliance**: Regulatory claims as BeliefArtifacts, audit
+  findings as failure modes, contradictory requirements as Logic Knots.
+
+References
+----------
+- AEE: https://appliedepistemicengineering.com/
+- ARE framework: https://github.com/organvm-i-theoria/auto-revision-epistemic-engine
+- VERITAS/CERTUS: https://github.com/AionSystem/VERITAS
+- AI as Epistemic Technology (Springer): https://doi.org/10.1007/s11948-023-00451-3
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+
+class ConfidenceLevel(str, Enum):
+    """Epistemic confidence assigned to a BeliefArtifact.
+
+    Maps to a numeric score used by CertaintyEngine:
+      UNKNOWN  → 0.0   (no evidence, new claim)
+      LOW      → 0.25  (asserted but not stress-tested)
+      MEDIUM   → 0.55  (stress-tested with minor failures resolved)
+      HIGH     → 0.85  (stress-tested, equilibrium reached, evidence present)
+    """
+
+    UNKNOWN = "unknown"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+    @property
+    def score(self) -> float:
+        """Numeric score for propagation calculations."""
+        return _CONFIDENCE_SCORES[self]
+
+
+_CONFIDENCE_SCORES: dict[ConfidenceLevel, float] = {
+    ConfidenceLevel.UNKNOWN: 0.0,
+    ConfidenceLevel.LOW: 0.25,
+    ConfidenceLevel.MEDIUM: 0.55,
+    ConfidenceLevel.HIGH: 0.85,
+}
+
+
+class BeliefStatus(str, Enum):
+    """Lifecycle status of a BeliefArtifact."""
+
+    DRAFT = "draft"
+    ACCEPTED = "accepted"
+    STRESS_TESTED = "stress-tested"
+    RECONSTRUCTED = "reconstructed"
+    DEPRECATED = "deprecated"
+
+
+class FailureSeverity(str, Enum):
+    """Severity of a failure mode in the Failure-Mode Graph."""
+
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+@dataclass
+class FailureMode:
+    """A single failure mode discovered by the StressTester.
+
+    Represents a stress-test → breakpoint relation in the Failure-Mode Graph G.
+    """
+
+    artifact_id: str
+    challenge: str
+    breakpoint: str
+    severity: FailureSeverity = FailureSeverity.MEDIUM
+    recovery_hint: str = ""
+    resolved: bool = False
+
+
+@dataclass
+class BeliefArtifact:
+    """A codable, testable, deployable unit of knowledge.
+
+    The fundamental unit of AEE. Can represent:
+    - A software requirement (REQ-CLI-001)
+    - A research hypothesis (HYP-IND-001)
+    - An architectural decision (DEC-001)
+    - A compliance claim (COMP-GDPR-001)
+    - Any structured belief that must be Observable and Falsifiable
+
+    Examples
+    --------
+    Software requirement::
+
+        req = BeliefArtifact(
+            artifact_id="REQ-API-001",
+            propositions=["The API must return HTTP 200 for valid requests"],
+            epistemic_boundary=["Platform: all", "Auth: JWT required"],
+            confidence=ConfidenceLevel.ACCEPTED,
+            status=BeliefStatus.ACCEPTED,
+        )
+
+    Research hypothesis::
+
+        hyp = BeliefArtifact(
+            artifact_id="HYP-IND-001",
+            propositions=["Indus script uses logosyllabic encoding",
+                          "Sign frequency distribution follows Zipf's law"],
+            epistemic_boundary=["Corpus: Mahadevan 2977 inscriptions, 1977"],
+            confidence=ConfidenceLevel.LOW,
+            status=BeliefStatus.ACCEPTED,
+        )
+    """
+
+    artifact_id: str
+    propositions: list[str] = field(default_factory=list)
+    epistemic_boundary: list[str] = field(default_factory=list)
+    inferential_links: list[str] = field(default_factory=list)
+    confidence: ConfidenceLevel = ConfidenceLevel.UNKNOWN
+    status: BeliefStatus = BeliefStatus.DRAFT
+    failure_modes: list[FailureMode] = field(default_factory=list)
+    source_text: str = ""
+    component: str = ""
+    priority: str = ""
+    # Optional metadata for non-specsmith uses
+    domain: str = ""  # e.g., "linguistics", "software", "policy"
+    evidence: list[str] = field(default_factory=list)  # evidence citations
+
+    @property
+    def is_accepted(self) -> bool:
+        return self.status in (
+            BeliefStatus.ACCEPTED,
+            BeliefStatus.STRESS_TESTED,
+            BeliefStatus.RECONSTRUCTED,
+        )
+
+    @property
+    def has_failures(self) -> bool:
+        return any(not fm.resolved for fm in self.failure_modes)
+
+    @property
+    def unresolved_failures(self) -> list[FailureMode]:
+        return [fm for fm in self.failure_modes if not fm.resolved]
+
+    @property
+    def critical_failures(self) -> list[FailureMode]:
+        return [
+            fm
+            for fm in self.failure_modes
+            if not fm.resolved and fm.severity == FailureSeverity.CRITICAL
+        ]
+
+    def add_evidence(self, citation: str) -> BeliefArtifact:
+        """Add an evidence citation and elevate confidence if appropriate.
+
+        Returns self for chaining.
+        """
+        self.evidence.append(citation)
+        if self.confidence == ConfidenceLevel.UNKNOWN and self.evidence:
+            self.confidence = ConfidenceLevel.LOW
+        return self
+
+    def to_dict(self) -> dict[str, object]:
+        """Serialise to a plain dict (JSON-compatible)."""
+        return {
+            "artifact_id": self.artifact_id,
+            "propositions": self.propositions,
+            "epistemic_boundary": self.epistemic_boundary,
+            "inferential_links": self.inferential_links,
+            "confidence": self.confidence.value,
+            "status": self.status.value,
+            "source_text": self.source_text,
+            "component": self.component,
+            "priority": self.priority,
+            "domain": self.domain,
+            "evidence": self.evidence,
+            "failure_count": len(self.failure_modes),
+            "critical_count": len(self.critical_failures),
+        }
+
+
+# ---------------------------------------------------------------------------
+# Markdown parser — converts REQUIREMENTS.md entries to BeliefArtifacts
+# ---------------------------------------------------------------------------
+
+_REQ_HEADING = re.compile(r"^#{1,3}\s+(REQ-([A-Z0-9_]+)-(\d+))\s*(?:—\s*(.+))?$")
+_FIELD_LINE = re.compile(r"^\s*-\s+\*\*(.+?)\*\*:\s*(.+)$")
+
+
+def parse_requirements_as_beliefs(path: Path) -> list[BeliefArtifact]:
+    """Parse a REQUIREMENTS.md file and return a list of BeliefArtifacts.
+
+    Works with both specsmith-generated REQUIREMENTS.md files and
+    any markdown file that uses REQ-COMPONENT-NNN heading format.
+    """
+    if not path.exists():
+        return []
+
+    content = path.read_text(encoding="utf-8")
+    artifacts: list[BeliefArtifact] = []
+    current: BeliefArtifact | None = None
+    current_desc = ""
+
+    for line in content.splitlines():
+        m = _REQ_HEADING.match(line)
+        if m:
+            if current is not None:
+                _finalise(current, current_desc)
+                artifacts.append(current)
+            req_id = m.group(1)
+            component = m.group(2)
+            desc_inline = m.group(4) or ""
+            current = BeliefArtifact(
+                artifact_id=req_id,
+                component=component,
+                source_text=desc_inline,
+            )
+            current_desc = desc_inline
+            continue
+
+        if current is None:
+            continue
+
+        fm = _FIELD_LINE.match(line)
+        if fm:
+            key = fm.group(1).lower()
+            val = fm.group(2).strip()
+            if key in ("description", "desc"):
+                current_desc = val
+                current.source_text = val
+            elif key == "priority":
+                current.priority = val
+            elif key == "status":
+                current.status = _map_status(val)
+                current.confidence = _infer_confidence(current.status)
+            elif key in ("platform", "platforms", "boundary"):
+                current.epistemic_boundary.append(f"{key.capitalize()}: {val}")
+            elif key == "domain":
+                current.domain = val
+            elif key == "evidence":
+                current.evidence.append(val)
+        else:
+            stripped = line.strip().lstrip("-").strip()
+            if stripped and not stripped.startswith("#") and not current_desc:
+                current_desc = stripped
+
+    if current is not None:
+        _finalise(current, current_desc)
+        artifacts.append(current)
+
+    return artifacts
+
+
+def beliefs_from_dicts(data: list[dict[str, object]]) -> list[BeliefArtifact]:
+    """Construct BeliefArtifacts from a list of plain dicts.
+
+    Useful when loading from JSON, YAML, or a database::
+
+        import yaml
+        data = yaml.safe_load(open("hypotheses.yml"))
+        artifacts = beliefs_from_dicts(data["beliefs"])
+    """
+    artifacts = []
+    for d in data:
+        a = BeliefArtifact(
+            artifact_id=str(d.get("artifact_id", "")),
+            propositions=list(d.get("propositions", [])),  # type: ignore[arg-type]
+            epistemic_boundary=list(d.get("epistemic_boundary", [])),  # type: ignore[arg-type]
+            inferential_links=list(d.get("inferential_links", [])),  # type: ignore[arg-type]
+            confidence=ConfidenceLevel(d.get("confidence", "unknown")),
+            status=BeliefStatus(d.get("status", "draft")),
+            source_text=str(d.get("source_text", "")),
+            component=str(d.get("component", "")),
+            priority=str(d.get("priority", "")),
+            domain=str(d.get("domain", "")),
+            evidence=list(d.get("evidence", [])),  # type: ignore[arg-type]
+        )
+        artifacts.append(a)
+    return artifacts
+
+
+def _finalise(artifact: BeliefArtifact, desc: str) -> None:
+    if not desc:
+        return
+    artifact.source_text = artifact.source_text or desc
+    parts = re.split(r";|\band\b(?=\s+[A-Z])", desc)
+    artifact.propositions = artifact.propositions or [p.strip() for p in parts if p.strip()]
+    if not artifact.epistemic_boundary:
+        artifact.epistemic_boundary = ["Assumed correct project environment"]
+
+
+def _map_status(val: str) -> BeliefStatus:
+    val_lower = val.lower()
+    if "accept" in val_lower:
+        return BeliefStatus.ACCEPTED
+    if "stress" in val_lower:
+        return BeliefStatus.STRESS_TESTED
+    if "reconstruct" in val_lower:
+        return BeliefStatus.RECONSTRUCTED
+    if "deprecat" in val_lower:
+        return BeliefStatus.DEPRECATED
+    return BeliefStatus.DRAFT
+
+
+def _infer_confidence(status: BeliefStatus) -> ConfidenceLevel:
+    return {
+        BeliefStatus.DRAFT: ConfidenceLevel.UNKNOWN,
+        BeliefStatus.ACCEPTED: ConfidenceLevel.LOW,
+        BeliefStatus.STRESS_TESTED: ConfidenceLevel.MEDIUM,
+        BeliefStatus.RECONSTRUCTED: ConfidenceLevel.HIGH,
+        BeliefStatus.DEPRECATED: ConfidenceLevel.LOW,
+    }.get(status, ConfidenceLevel.UNKNOWN)
+
+
+__all__ = [
+    "BeliefArtifact",
+    "BeliefStatus",
+    "ConfidenceLevel",
+    "FailureMode",
+    "FailureSeverity",
+    "parse_requirements_as_beliefs",
+    "beliefs_from_dicts",
+]