othismos 0.4.0__py3-none-any.whl

othismos/__init__.py

@@ -0,0 +1,156 @@
+# Óthismos — Core Library
+#
+# The force a bounded system exerts against its bounds.
+# The push IS the knowing.
+
+from othismos.protocols import (
+    FeasibilityFn,
+    ProjectionFn,
+    NormalFn,
+    DistanceFn,
+    ConstraintLike,
+)
+from othismos.config import OthismosConfig
+from othismos.pressure import (
+    ConstraintType,
+    Constraint,
+    PressureMeasurement,
+    PressureGauge,
+    GoldilocksZone,
+    compute_othismos,
+    goldilocks_range,
+    l2_constraint,
+    box_constraint,
+)
+from othismos.phases import (
+    MoltPhase,
+    PhaseClassifier,
+    PhaseReading,
+    MoltCycle,
+    MoltCycleTracker,
+)
+from othismos.diagnostics import (
+    DiagnosticResult,
+    PopcornDiagnostic,
+    SystemHealth,
+)
+from othismos.ecology import (
+    Deposit,
+    Reef,
+    ReefLayer,
+    Reefquake,
+)
+from othismos.integrations import (
+    MetricLogger,
+    DictLogger,
+    OthismosTorchCallback,
+    OthismosTrainerCallback,
+    constraint_from_torch_model,
+)
+from othismos.context_pressure import (
+    ContextPressureGauge,
+    ContextPressureMeasurement,
+    cosine_distance,
+    l2_distance,
+    token_overlap,
+)
+from othismos.controller import (
+    PressureController,
+    ControlAction,
+    ActionType,
+)
+from othismos.serialization import (
+    save_history,
+    load_history,
+    save_diagnostic,
+    export_metrics_csv,
+    pressure_summary,
+)
+
+# Optional imports (require extra deps)
+try:
+    from othismos.viz import (
+        plot_pressure,
+        plot_molt_cycle,
+        plot_constraint_profile,
+        plot_diagnostic_timeline,
+    )
+except ImportError:
+    pass
+
+try:
+    from othismos.pandas_export import (
+        gauge_to_dataframe,
+        tracker_to_dataframe,
+        reef_to_dataframe,
+    )
+except ImportError:
+    pass
+
+__version__ = "0.4.0"
+__all__ = [
+    # Protocols
+    "FeasibilityFn",
+    "ProjectionFn",
+    "NormalFn",
+    "DistanceFn",
+    "ConstraintLike",
+    # Config
+    "OthismosConfig",
+    # Pressure
+    "ConstraintType",
+    "Constraint",
+    "PressureMeasurement",
+    "PressureGauge",
+    "GoldilocksZone",
+    "compute_othismos",
+    "goldilocks_range",
+    "l2_constraint",
+    "box_constraint",
+    # Phases
+    "MoltPhase",
+    "PhaseClassifier",
+    "PhaseReading",
+    "MoltCycle",
+    "MoltCycleTracker",
+    # Diagnostics
+    "DiagnosticResult",
+    "PopcornDiagnostic",
+    "SystemHealth",
+    # Ecology
+    "Deposit",
+    "Reef",
+    "ReefLayer",
+    "Reefquake",
+    # Integrations
+    "MetricLogger",
+    "DictLogger",
+    "OthismosTorchCallback",
+    "OthismosTrainerCallback",
+    "constraint_from_torch_model",
+    # Context pressure
+    "ContextPressureGauge",
+    "ContextPressureMeasurement",
+    "cosine_distance",
+    "l2_distance",
+    "token_overlap",
+    # Controller
+    "PressureController",
+    "ControlAction",
+    "ActionType",
+    # Serialization
+    "save_history",
+    "load_history",
+    "save_diagnostic",
+    "export_metrics_csv",
+    "pressure_summary",
+    # Viz (optional)
+    "plot_pressure",
+    "plot_molt_cycle",
+    "plot_constraint_profile",
+    "plot_diagnostic_timeline",
+    # Pandas (optional)
+    "gauge_to_dataframe",
+    "tracker_to_dataframe",
+    "reef_to_dataframe",
+]

othismos/cli.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+"""
+othismos — CLI for measuring constraint pressure in bounded systems.
+
+Usage:
+    othismos pressure <model_dir> [--constraints config.yaml]
+    othismos reef <action> [--db reef.json]
+    othismos reef add <id> <content> [--refs id1,id2]
+    othismos reef list [--layer surface|consolidation|foundation]
+    othismos reef fail <id>
+    othismos reef stats
+    othismos diagnose <history.json> [--heat 1.0]
+    othismos version
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from othismos import (
+    PressureGauge,
+    PopcornDiagnostic,
+    Reef,
+    ReefLayer,
+    Reefquake,
+    SystemHealth,
+    __version__,
+    pressure_summary,
+    save_history,
+    load_history,
+)
+
+
+# ─── Pressure Commands ────────────────────────────────────────────
+
+def cmd_pressure(args):
+    """Analyze pressure data from a saved history."""
+    if not args.history:
+        print("Error: --history required (JSON file from save_history)")
+        sys.exit(1)
+
+    gauge = load_history(args.history)
+    summary = pressure_summary(gauge)
+
+    print("\n=== Pressure Analysis ===\n")
+    for k, v in summary.items():
+        if isinstance(v, dict):
+            print(f"  {k}:")
+            for sk, sv in v.items():
+                print(f"    {sk}: {sv:.6f}")
+        else:
+            print(f"  {k}: {v}")
+
+
+# ─── Reef Commands ────────────────────────────────────────────────
+
+REEF_DB_DEFAULT = ".othismos-reef.json"
+
+
+def _load_reef(path: str) -> Reef:
+    """Load a reef from a JSON snapshot (or create new)."""
+    reef = Reef()
+    p = Path(path)
+    if p.exists():
+        data = json.loads(p.read_text())
+        for dep_data in data.get("deposits", []):
+            reef.submit(
+                dep_data["id"],
+                dep_data["content"],
+                references=dep_data.get("references", []),
+            )
+            # Restore age and layer
+            if dep_data.get("age"):
+                dep = reef.query(dep_data["id"])
+                if dep:
+                    dep.age = dep_data["age"]
+    return reef
+
+
+def _save_reef(reef: Reef, path: str):
+    """Save a reef to JSON."""
+    deposits = []
+    for dep_id in list(reef._deposits.keys()):
+        dep = reef._deposits[dep_id]
+        deposits.append({
+            "id": dep.id,
+            "content": dep.content,
+            "references": dep.references,
+            "referenced_by": list(dep.referenced_by),
+            "layer": dep.layer.name,
+            "age": dep.age,
+            "depth_score": dep.depth_score,
+        })
+    data = {
+        "version": __version__,
+        "step": reef.step,
+        "deposits": deposits,
+    }
+    Path(path).write_text(json.dumps(data, indent=2))
+
+
+def cmd_reef(args):
+    """Manage a local knowledge reef."""
+    db_path = args.db or REEF_DB_DEFAULT
+
+    if args.action == "add":
+        reef = _load_reef(db_path)
+        refs = args.refs.split(",") if args.refs else []
+        accepted, msg = reef.submit(args.id, args.content, references=refs)
+        if accepted:
+            _save_reef(reef, db_path)
+            print(f"✓ {msg}")
+        else:
+            print(f"✗ {msg}")
+            sys.exit(1)
+
+    elif args.action == "list":
+        reef = _load_reef(db_path)
+        layer_filter = args.layer.upper() if args.layer else None
+
+        deposits = []
+        for dep in reef._deposits.values():
+            if layer_filter and dep.layer.name != layer_filter:
+                continue
+            deposits.append(dep)
+
+        deposits.sort(key=lambda d: (-d.depth_score, d.id))
+
+        if not deposits:
+            print("(empty reef)")
+            return
+
+        print(f"\n{'ID':<20} {'Layer':<15} {'Refs':<6} {'Age':<6} {'Depth':<8} Content")
+        print("-" * 90)
+        for dep in deposits:
+            content_preview = dep.content[:40] + ("..." if len(dep.content) > 40 else "")
+            print(f"{dep.id:<20} {dep.layer.name:<15} {dep.reference_count:<6} {dep.age:<6} {dep.depth_score:<8.1f} {content_preview}")
+
+    elif args.action == "fail":
+        reef = _load_reef(db_path)
+        try:
+            reef.fail_deposit(args.id)
+        except Reefquake as rq:
+            _save_reef(reef, db_path)
+            print(f"⚠️  REEFQUAKE: deposit '{rq.failed_id}' failed!")
+            print(f"   {len(rq.affected)} deposits removed:")
+            for dep_id in rq.affected:
+                print(f"   - {dep_id}")
+        except KeyError:
+            print(f"✗ Unknown deposit: {args.id}")
+            sys.exit(1)
+
+    elif args.action == "stats":
+        reef = _load_reef(db_path)
+        summary = reef.summary()
+        print("\n=== Reef Statistics ===\n")
+        for k, v in summary.items():
+            if isinstance(v, dict):
+                print(f"  {k}:")
+                for sk, sv in v.items():
+                    print(f"    {sk}: {sv}")
+            else:
+                print(f"  {k}: {v}")
+
+    elif args.action == "tick":
+        reef = _load_reef(db_path)
+        result = reef.tick()
+        _save_reef(reef, db_path)
+        print(f"Step {result['step']}: {result['total_deposits']} deposits")
+        if result["eroded"]:
+            print(f"  Eroded: {', '.join(result['eroded'])}")
+        if result["promoted"]:
+            for dep_id, layer in result["promoted"]:
+                print(f"  Promoted: {dep_id} → {layer}")
+
+    elif args.action == "search":
+        reef = _load_reef(db_path)
+        results = reef.search(args.query)
+        if not results:
+            print("(no results)")
+            return
+        for dep in results:
+            print(f"\n  {dep.id} (depth={dep.depth_score:.1f}, layer={dep.layer.name})")
+            print(f"  {dep.content[:200]}")
+
+    elif args.action == "graph":
+        reef = _load_reef(db_path)
+        graph = reef.citation_graph()
+        print(json.dumps(graph, indent=2))
+
+    else:
+        print(f"Unknown reef action: {args.action}")
+        sys.exit(1)
+
+
+# ─── Diagnose Commands ────────────────────────────────────────────
+
+def cmd_diagnose(args):
+    """Run popcorn diagnostic on saved pressure data."""
+    gauge = load_history(args.history)
+    pressures = [m.pressure for m in gauge.history]
+
+    diag = PopcornDiagnostic()
+    result = diag.diagnose(pressures, heat=args.heat)
+
+    health_emoji = {
+        SystemHealth.POP: "🍿",
+        SystemHealth.BURN: "🔥",
+        SystemHealth.SEEP: "💧",
+        SystemHealth.DORMANT: "😴",
+    }
+
+    print(f"\n{health_emoji.get(result.health, '?')} Health: {result.health.value.upper()}")
+    print(f"   Confidence: {result.confidence:.0%}")
+    print(f"   Pressure: {result.pressure:.6f}")
+    print(f"   Heat: {result.heat:.6f}")
+    print(f"   Efficiency: {result.pressure_efficiency:.4f}")
+    print()
+    for signal in result.signals:
+        print(f"   → {signal}")
+    print()
+    print(f"   {result.recommendation}")
+
+
+# ─── Main ─────────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="othismos",
+        description="Measure constraint pressure in bounded systems. The push IS the knowing.",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    # Pressure
+    p_pressure = sub.add_parser("pressure", help="Analyze pressure history")
+    p_pressure.add_argument("--history", help="JSON file from save_history")
+    p_pressure.set_defaults(func=cmd_pressure)
+
+    # Reef
+    p_reef = sub.add_parser("reef", help="Manage a knowledge reef")
+    p_reef.add_argument("action", choices=["add", "list", "fail", "stats", "tick", "search", "graph"])
+    p_reef.add_argument("id", nargs="?", help="Deposit ID (for add/fail)")
+    p_reef.add_argument("content", nargs="?", help="Deposit content (for add)")
+    p_reef.add_argument("--refs", help="Comma-separated reference IDs (for add)")
+    p_reef.add_argument("--layer", choices=["surface", "consolidation", "foundation"])
+    p_reef.add_argument("--query", help="Search query (for search action)")
+    p_reef.add_argument("--db", help=f"Reef database path (default: {REEF_DB_DEFAULT})")
+    p_reef.set_defaults(func=cmd_reef)
+
+    # Diagnose
+    p_diag = sub.add_parser("diagnose", help="Run popcorn diagnostic")
+    p_diag.add_argument("history", help="JSON file from save_history")
+    p_diag.add_argument("--heat", type=float, default=1.0, help="Current external pressure")
+    p_diag.set_defaults(func=cmd_diagnose)
+
+    # Version
+    p_version = sub.add_parser("version", help="Print version")
+    p_version.set_defaults(func=lambda a: print(f"othismos {__version__}"))
+
+    args = parser.parse_args()
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

othismos/config.py

@@ -0,0 +1,131 @@
+"""
+Configuration objects for óthismos.
+
+Single dataclass to configure gauge + tracker + diagnostic + controller
+together. Supports YAML/dict construction for config-file-driven workflows.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from typing import Any
+
+
+@dataclass(slots=True)
+class OthismosConfig:
+    """Configuration for the full óthismos monitoring stack.
+
+    Pass to PressureGauge, MoltCycleTracker, PopcornDiagnostic, and
+    PressureController to ensure consistent settings.
+
+    Example:
+        >>> config = OthismosConfig(crisis_threshold=0.5, window_size=5000)
+        >>> gauge = PressureGauge(window_size=config.window_size)
+        >>> classifier = PhaseClassifier(
+        ...     crisis_threshold=config.crisis_threshold,
+        ...     expansion_floor=config.expansion_floor,
+        ... )
+
+    Or from dict/YAML:
+        >>> config = OthismosConfig.from_dict({"crisis_threshold": 0.5})
+        >>> config = OthismosConfig.from_yaml("config.yaml")
+    """
+
+    # Pressure gauge
+    window_size: int = 1000
+
+    # Phase classifier
+    crisis_threshold: float | None = None
+    expansion_floor: float | None = None
+    settlement_decline_rate: float = -0.5
+
+    # Popcorn diagnostic
+    burn_threshold: float = 0.01
+    seep_volatility: float = 0.5
+    pop_efficiency: float = 0.3
+
+    # Controller
+    lr_bounds: tuple[float, float] = (1e-6, 1.0)
+    crisis_lr_factor: float = 0.5
+    expansion_lr_factor: float = 1.3
+    burn_patience: int = 50
+
+    # Logging
+    log_every: int = 1
+    log_backend: str = "dict"  # dict | wandb | tensorboard | stdout
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "OthismosConfig":
+        """Create config from a dictionary."""
+        valid = {k: v for k, v in data.items() if k in cls.__annotations__ or k in cls.__dataclass_fields__}
+        return cls(**valid)
+
+    @classmethod
+    def from_yaml(cls, path: str) -> "OthismosConfig":
+        """Create config from a YAML file."""
+        import yaml
+        with open(path) as f:
+            data = yaml.safe_load(f)
+        return cls.from_dict(data or {})
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize config to dict."""
+        return asdict(self)
+
+    def to_yaml(self, path: str) -> None:
+        """Write config to a YAML file."""
+        import yaml
+        with open(path, "w") as f:
+            yaml.safe_dump(self.to_dict(), f, default_flow_style=False)
+
+    def build_gauge(self):
+        """Construct a PressureGauge from this config."""
+        from othismos.pressure import PressureGauge
+        return PressureGauge(window_size=self.window_size)
+
+    def build_classifier(self):
+        """Construct a PhaseClassifier from this config."""
+        from othismos.phases import PhaseClassifier
+        return PhaseClassifier(
+            crisis_threshold=self.crisis_threshold,
+            expansion_floor=self.expansion_floor,
+            settlement_decline_rate=self.settlement_decline_rate,
+        )
+
+    def build_diagnostic(self):
+        """Construct a PopcornDiagnostic from this config."""
+        from othismos.diagnostics import PopcornDiagnostic
+        return PopcornDiagnostic(
+            burn_threshold=self.burn_threshold,
+            seep_volatility=self.seep_volatility,
+            pop_efficiency=self.pop_efficiency,
+        )
+
+    def build_controller(self, gauge=None, tracker=None):
+        """Construct a PressureController from this config."""
+        from othismos.controller import PressureController
+        from othismos.phases import MoltCycleTracker
+        gauge = gauge or self.build_gauge()
+        tracker = tracker or MoltCycleTracker(classifier=self.build_classifier())
+        return PressureController(
+            gauge=gauge,
+            tracker=tracker,
+            lr_bounds=self.lr_bounds,
+            crisis_lr_factor=self.crisis_lr_factor,
+            expansion_lr_factor=self.expansion_lr_factor,
+            burn_patience=self.burn_patience,
+        )
+
+    def build_all(self):
+        """Build the full stack: gauge, tracker, diagnostic, controller.
+
+        Returns:
+            (gauge, tracker, diagnostic, controller)
+        """
+        gauge = self.build_gauge()
+        classifier = self.build_classifier()
+        from othismos.phases import MoltCycleTracker
+        tracker = MoltCycleTracker(classifier=classifier)
+        diagnostic = self.build_diagnostic()
+        controller = self.build_controller(gauge=gauge, tracker=tracker)
+        return gauge, tracker, diagnostic, controller