speclogician 0.0.0b1__py3-none-any.whl

speclogician/utils/__init__.py

@@ -0,0 +1,78 @@
+#
+#   Imandra Inc.
+#
+#   utils/__init__.py
+#
+
+from __future__ import annotations
+
+import os
+import json
+import typer
+from typing import Any, TypeAlias
+from enum import Enum, StrEnum
+from rich.console import Console
+from rich.theme import Theme
+
+IMANDRA_KEY_ENV = "IMANDRA_UNI_KEY"
+
+
+console = Console(
+    force_terminal=True, 
+    color_system="truecolor", 
+    theme=Theme({"info": "cyan", "ok": "green", "warn": "yellow", "err": "red"})
+)
+
+class IMLValidity (StrEnum):
+    VALID = 'valid'
+    INVALID = 'invalid'
+    UNKNOWN = 'unknown'
+
+
+JSONScalar: TypeAlias = str | int | float | bool | None
+JSONValue: TypeAlias = JSONScalar | list["JSONValue"] | dict[str, "JSONValue"]
+JSONObject: TypeAlias = dict[str, JSONValue]
+
+
+def emit_json(obj: JSONObject) -> None:
+    """
+    Print JSON (never exits).
+    Use this only at the CLI boundary or for debugging.
+    """
+    typer.echo(json.dumps(obj, indent=2, default=_json_default))
+
+
+def _json_default(o: Any) -> Any:
+    # Enums (BaseStatus, PredicateType, etc)
+    if isinstance(o, Enum):
+        return o.value
+    # datetime, Path, etc (best-effort string)
+    try:
+        return str(o)
+    except Exception:
+        return repr(o)
+
+def require_imandra_key() -> None:
+    """
+    Ensure IMANDRA_UNI_KEY is present in the environment.
+    Exit the CLI with a clear message if not.
+    """
+    key = os.getenv(IMANDRA_KEY_ENV)
+
+    if not key:
+        console.print(
+            "[red]✖ ImandraX API key missing[/red]\n\n"
+            "SpecLogician requires an Imandra Universe API key to run.\n\n"
+            "Please set the environment variable:\n\n"
+            f"  export {IMANDRA_KEY_ENV}=<your-api-key>\n\n"
+            "You can obtain a key from Imandra Universe."
+        )
+        raise typer.Exit(code=2)
+
+__all__ = [
+    "require_imandra_key",
+    "emit_json",
+    "_json_default",
+    "IMLValidity",
+    "console"
+]

speclogician/utils/load.py

@@ -0,0 +1,166 @@
+#
+#   Imandra Inc.
+#
+#   speclogician/utils/load.py
+#
+
+import json
+import os
+from pathlib import Path
+
+import typer
+from typing import NoReturn
+from rich.prompt import Prompt
+
+from ..state.state import State
+from .__init__ import console
+
+
+def _emit_json(obj: dict, exit_code: int = 0) -> NoReturn:
+    """Print JSON and exit (useful for CLI / tests)."""
+    typer.echo(json.dumps(obj, indent=2))
+    raise typer.Exit(code=exit_code)
+
+
+def load_state(path: Path | None = None, json: bool = False) -> State:
+    """
+    Load a State either from an explicit JSON path or from the local directory.
+
+    - If `path` is provided:
+        * if it exists: load JSON from it
+        * if it doesn't exist: ask to create it (unless json)
+    - If `path` is None:
+        * load from current directory via State.from_dir()
+        * if missing: ask to create it (unless json)
+
+    If json=True:
+      - emit JSON on success/error and Exit (no prompts).
+    """
+    cwd = Path(os.getcwd())
+
+    def create_new_state(target: Path | None) -> State:
+        """
+        Create a new state and persist it.
+        NOTE: Your State.save() appears to accept a directory path; we use:
+          - cwd when target is None
+          - target.parent when target is a file path
+        """
+        state = State()
+
+        if target is None:
+            state.save(str(cwd))
+            return state
+
+        target = target.expanduser()
+        target.parent.mkdir(parents=True, exist_ok=True)
+        state.save(str(target.parent))
+        return state
+
+    # -------------------------
+    # Case 1: explicit file path
+    # -------------------------
+    if path is not None:
+        path = path.expanduser()
+
+        if path.exists():
+            try:
+                if path.is_dir():
+                    new_state = State.from_dir(dirpath=path)
+                else:
+                    new_state = State.from_json(path.read_text())
+            except Exception as e:
+                if json:
+                    _emit_json(
+                        {
+                            "ok": False,
+                            "error": "failed_to_load_state_json",
+                            "path": str(path),
+                            "message": str(e),
+                        },
+                        exit_code=2,
+                    )
+                console.print(f"[red]Failed to load state JSON:[/] {path}\n{e}")
+                raise
+
+            if json:
+                _emit_json(
+                    {"ok": True, "source": "state_json", "path": str(path)},
+                    exit_code=0,
+                )
+            return new_state
+
+        # File doesn't exist
+        if json:
+            _emit_json(
+                {
+                    "ok": False,
+                    "error": "state_json_not_found",
+                    "path": str(path),
+                    "message": "State JSON file does not exist.",
+                },
+                exit_code=2,
+            )
+
+        answer = Prompt.ask(
+            prompt=f"⚠️ State file not found at {path}. Create a new one?",
+            choices=["Yes", "No"],
+            console=console,
+            case_sensitive=False,
+            default="Yes",
+        )
+        if answer.lower() == "no":
+            console.print("Goodbye!")
+            raise typer.Exit(0)
+
+        console.print("Creating a new state!")
+        return create_new_state(path)
+
+    # -------------------------
+    # Case 2: default local dir
+    # -------------------------
+    try:
+        new_state = State.from_dir(dirpath=str(cwd))
+    except Exception as e:
+        if json:
+            _emit_json(
+                {
+                    "ok": False,
+                    "error": "failed_to_load_state_from_dir",
+                    "dir": str(cwd),
+                    "message": str(e),
+                },
+                exit_code=2,
+            )
+        console.print(f"[red]Failed to load state from directory:[/] {cwd}\n{e}")
+        raise
+
+    if new_state is not None:
+        if json:
+            _emit_json({"ok": True, "source": "dir", "dir": str(cwd)}, exit_code=0)
+        return new_state
+
+    # Not found in cwd
+    if json:
+        _emit_json(
+            {
+                "ok": False,
+                "error": "state_not_found_in_dir",
+                "dir": str(cwd),
+                "message": "No state found in current directory.",
+            },
+            exit_code=2,
+        )
+
+    answer = Prompt.ask(
+        prompt="⚠️ Couldn't find a state in current directory. Create a new one?",
+        choices=["Yes", "No"],
+        console=console,
+        case_sensitive=False,
+        default="Yes",
+    )
+    if answer.lower() == "no":
+        console.print("Goodbye!")
+        raise typer.Exit(0)
+
+    console.print("Creating a new state!")
+    return create_new_state(None)

speclogician/utils/prompt.md

@@ -0,0 +1,325 @@
+# SpecLogician Agent Playbook
+## Formal Reasoning Copilot for Code, Finance, and Contracts
+
+---
+
+## 1. Purpose and Audience
+
+This playbook is written for **LLM-based coding and reasoning agents**
+(Claude Code, Copilot, Cursor, internal agents) operating alongside:
+
+- **SpecLogician** (stateful specification + analysis loop)
+- **CodeLogician** (code → formal model translation)
+- **ImandraX** (symbolic reasoning, decomposition, complement analysis)
+
+The goal is to enable **trustworthy, auditable, and logically complete workflows**
+for regulated and high‑assurance domains:
+- Software systems
+- Financial models
+- Risk engines
+- M&A and regulatory contracts
+- Protocols and workflows
+
+You are not a text editor.
+You are a **formal reasoning copilot**.
+
+---
+
+## 2. Core Mental Model
+
+SpecLogician maintains an **immutable state history**.
+
+Each change:
+- Produces a new `StateInstance`
+- Triggers logical analysis
+- Produces a structured `state_diff`
+
+A state consists of:
+
+```
+State
+ ├─ Spec
+ │   ├─ Domain Model
+ │   │   ├─ Base (types + core invariants, IML)
+ │   │   ├─ State Predicates
+ │   │   ├─ Action Predicates
+ │   │   └─ Transitions
+ │   ├─ Scenarios (Given / When / Then)
+ │   └─ Scenario Complement (coverage)
+ ├─ Artifact Container
+ │   ├─ Test Traces
+ │   ├─ Log Traces
+ │   ├─ Documents
+ │   └─ Source References
+ ├─ Artifact Mapping
+ ├─ Derived Stats
+ └─ StateDiff (vs previous state)
+```
+
+Nothing mutates in place.
+Progress is measured by **diffs and coverage**, not by edits.
+
+---
+
+## 3. The Agent Loop (Golden Path)
+
+Every successful interaction follows this loop:
+
+1. **Inspect**
+   ```bash
+   speclogician view state
+   speclogician view diff
+   ```
+
+2. **Diagnose**
+   - Missing predicates?
+   - Inconsistent scenarios?
+   - Large complement?
+   - Traces not matching scenarios?
+
+3. **Search**
+   ```bash
+   speclogician find predicates <query>
+   speclogician find transitions <query>
+   speclogician find artifacts <query>
+   ```
+
+4. **Apply exactly ONE change**
+   ```bash
+   speclogician ch ...
+   ```
+
+5. **Re‑inspect**
+   ```bash
+   speclogician view diff
+   ```
+
+6. **Repeat**
+
+> One change. One diff. One improvement.
+
+---
+
+## 4. Change Commands (`speclogician ch`)
+
+### 4.1 Domain Base
+
+Defines the semantic universe.
+
+```bash
+speclogician ch base-edit --src "type state = { x:int }
+type action = int"
+```
+
+Rules:
+- Must be valid IML
+- Breaks everything downstream if wrong
+- Complement is gated on base validity
+
+---
+
+### 4.2 Predicates
+
+Predicates define **classifications**, not behavior.
+
+```bash
+speclogician ch pred-add   --pred-type STATE   --pred-name is_large_trade   --pred-src "s.amount > 1_000_000"
+```
+
+Types:
+- STATE: properties of state
+- ACTION: properties of actions
+
+---
+
+### 4.3 Transitions
+
+Transitions define **state evolution**.
+
+```bash
+speclogician ch trans-add   --trans-name execute   --trans-src "let execute (s:state) (a:action) = { amount = s.amount + a }"
+```
+
+---
+
+### 4.4 Scenarios
+
+Scenarios define **intended behaviors**.
+
+```bash
+speclogician ch scenario-add trade_exec   --given is_authorized   --when place_order   --then execute
+```
+
+Scenarios:
+- Are partial specifications
+- Do not need to be complete
+- Drive complement reasoning
+
+---
+
+### 4.5 Traces
+
+Traces are **concrete evidence**.
+
+```bash
+speclogician ch trace test-add   --art-id T1   --name test_large_trade   --given "{ amount = 2_000_000 }"   --when "{ order = BUY }"   --then "{ approved = true }"
+```
+
+Traces validate scenarios but **do not replace them**.
+
+---
+
+## 5. View Commands (`speclogician view`)
+
+Most important commands:
+
+```bash
+speclogician view diff
+speclogician view spec
+speclogician view domain
+speclogician view artifacts
+```
+
+Rules:
+- Always inspect `view diff`
+- Treat diffs as first‑class artifacts
+- Never assume success without checking
+
+---
+
+## 6. Search Commands (`speclogician find`)
+
+Use search before modification.
+
+```bash
+speclogician find predicates limit --kind state
+speclogician find transitions approve
+speclogician find artifacts margin --kind docs
+```
+
+Search prevents duplicate logic and drift.
+
+---
+
+## 7. Complement & Coverage
+
+The **scenario complement** represents:
+> All logically possible behaviors not covered by scenarios.
+
+Properties:
+- Computed via ImandraX
+- Semantic (not test‑based)
+- Shrinking complement = progress
+
+Signals:
+- No complement → base or scenarios invalid
+- Large complement → missing intent
+- Empty complement → specification is complete (rare, valuable)
+
+---
+
+## 8. Worked Example 1: Minimal State Machine
+
+### Goal
+Model a simple counter with increment.
+
+**Base**
+```bash
+speclogician ch base-edit --src "type state = { x:int }
+type action = int"
+```
+
+**Predicate**
+```bash
+speclogician ch pred-add --pred-type STATE --pred-name nonneg --pred-src "s.x >= 0"
+```
+
+**Transition**
+```bash
+speclogician ch trans-add --trans-name inc --trans-src "let inc s a = { x = s.x + a }"
+```
+
+**Scenario**
+```bash
+speclogician ch scenario-add inc_ok --given nonneg --then inc
+```
+
+Inspect:
+```bash
+speclogician view diff
+```
+
+Complement highlights:
+- What about negative actions?
+- What about overflow?
+
+Add scenarios accordingly.
+
+---
+
+## 9. Worked Example 2: Financial Rule
+
+### Rule
+Large trades require approval.
+
+**Predicate**
+```bash
+speclogician ch pred-add --pred-type STATE --pred-name large_trade --pred-src "s.amount > 1_000_000"
+```
+
+**Scenario**
+```bash
+speclogician ch scenario-add approval_required --given large_trade --then approve
+```
+
+Complement reveals:
+- Small trades?
+- Large trades without approval?
+- Conflicting predicates?
+
+This is logic discovery, not testing.
+
+---
+
+## 10. Domains Beyond Code
+
+This workflow applies unchanged to:
+
+- M&A contracts (conditions, obligations, breaches)
+- Financial models (risk regions, limits)
+- Regulatory logic (must/must-not rules)
+- Protocols (valid/invalid sequences)
+
+Replace:
+- state → contract state
+- action → event
+- transition → clause effect
+
+---
+
+## 11. What NOT To Do
+
+❌ Edit files directly  
+❌ Apply multiple changes at once  
+❌ Ignore `state_diff`  
+❌ Confuse tests with coverage  
+❌ Assume LLM intuition equals correctness  
+
+---
+
+## 12. Final Agent Instructions
+
+You are a **reasoning engine supervisor**.
+
+Every step must:
+- Be justified by `view` or `find`
+- Produce a measurable `state_diff`
+- Reduce inconsistency or complement
+- Increase confidence and auditability
+
+If unsure:
+- Inspect more
+- Ask for clarification
+- Apply the smallest possible change
+
+Formal reasoning is a process, not a jump.

speclogician/utils/testing.py

@@ -0,0 +1,151 @@
+#
+#   Imandra Inc.
+#
+#   speclogician/utils/testing.py
+#
+
+from .__init__ import JSONObject, JSONValue
+
+import json
+from typing import cast
+from click.testing import Result
+
+# -----------------------
+# JSON parsing + narrowing helpers
+# -----------------------
+
+def parse_json_result(res : Result) -> JSONObject:
+    """
+    Parse JSON from CLI output.
+
+    If stdout is empty (Typer/Pydantic failed before we could emit JSON),
+    return a synthetic JSON error object so tests can assert consistently.
+    """
+    out = (res.stdout or "").strip()
+
+    if not out:
+        # Pre-command failure (argument parsing / Pydantic validation / Typer)
+        # Normalize into the same "result envelope" your CLI emits.
+        exc_s = ""
+        if res.exception is not None:
+            exc_s = str(res.exception)
+        elif res.output:
+            exc_s = str(res.output)
+
+        return cast(
+            JSONObject,
+            {
+                "ok": False,
+                "stage": "cli_parse",
+                "error": exc_s,
+            },
+        )
+
+    try:
+        data = json.loads(out)
+    except json.JSONDecodeError as e:
+        raise AssertionError(
+            "Failed to decode JSON from stdout.\n"
+            f"exit_code={res.exit_code}\n"
+            f"stdout={res.stdout!r}\n"
+            f"stderr={res.stderr!r}\n"
+            f"output={res.output!r}\n"
+            f"exception={res.exception!r}\n"
+            f"json_error={e}\n"
+        ) from e
+
+    # Ensure it's a dict-like JSON object
+    if not isinstance(data, dict):
+        raise AssertionError(f"Expected JSON object, got: {type(data).__name__}: {data!r}")
+
+    return cast(JSONObject, data)
+
+def get_change(data: JSONObject) -> JSONObject:
+    """
+    New CLI JSON wraps the change in {"ok": ..., "change": {...}, ...}.
+    Also accept legacy where the change was top-level.
+    """
+    chg = data.get("change")
+    if isinstance(chg, dict):
+        return cast(JSONObject, chg)
+    return data
+
+
+def _as_object(v: JSONValue, *, ctx: str = "value") -> JSONObject:
+    if not isinstance(v, dict):
+        raise AssertionError(f"Expected object for {ctx}, got {type(v).__name__}: {v!r}")
+    return cast(JSONObject, v)
+
+
+def _as_str(v: JSONValue, *, ctx: str = "value") -> str:
+    if not isinstance(v, str):
+        raise AssertionError(f"Expected string for {ctx}, got {type(v).__name__}: {v!r}")
+    return v
+
+
+def _as_bool(v: JSONValue, *, ctx: str = "value") -> bool:
+    if not isinstance(v, bool):
+        raise AssertionError(f"Expected bool for {ctx}, got {type(v).__name__}: {v!r}")
+    return v
+
+
+def _as_str_list(v: JSONValue, *, ctx: str = "value") -> list[str]:
+    if not isinstance(v, list) or not all(isinstance(x, str) for x in v):
+        raise AssertionError(f"Expected list[str] for {ctx}, got: {v!r}")
+    return cast(list[str], v)
+
+
+# -----------------------
+# Change payload accessors
+# -----------------------
+
+def chg_kind(chg: JSONObject) -> str | None:
+    v = chg.get("kind")
+    if v is None:
+        return None
+    return _as_str(v, ctx="change.kind")
+
+
+def chg_scenario_name(chg: JSONObject) -> str:
+    return _as_str(chg.get("scenario_name"), ctx="change.scenario_name")
+
+
+def delta_add(chg: JSONObject, field: str) -> list[str]:
+    """
+    field is one of: "given", "when", "then"
+    """
+    obj = _as_object(chg.get(field), ctx=f"change.{field}")
+    return _as_str_list(obj.get("add"), ctx=f"change.{field}.add")
+
+
+def delta_remove(chg: JSONObject, field: str) -> list[str]:
+    obj = _as_object(chg.get(field), ctx=f"change.{field}")
+    return _as_str_list(obj.get("remove"), ctx=f"change.{field}.remove")
+
+
+def result_ok(data: JSONObject) -> bool:
+    return _as_bool(data.get("ok"), ctx="result.ok")
+
+
+def result_stage(data: JSONObject) -> str | None:
+    v = data.get("stage")
+    if v is None:
+        return None
+    return _as_str(v, ctx="result.stage")
+
+
+def result_error_str(data: JSONObject) -> str:
+    """
+    Your JSON-safe error is a JSONObject (per your typing), but for tests we usually
+    want a stable string. This extracts a string in a robust way.
+    Adjust if your error schema is richer (e.g. {"message": "...", "type": "..."}).
+    """
+    err = data.get("error")
+    if err is None:
+        return ""
+    if isinstance(err, str):
+        return err
+    if isinstance(err, dict) and isinstance(err.get("message"), str):
+        return cast(str, err["message"])
+    # fallback: stable stringify
+    return json.dumps(cast(JSONValue, err))