speclogician 0.0.0b1__py3-none-any.whl

speclogician/main.py

@@ -0,0 +1,139 @@
+#
+#   Imandra Inc.
+#
+#   speclogician/main.py
+#
+
+__version__ = "1.0"
+
+import typer
+from typing import Final
+from pathlib import Path
+
+from speclogician.commands import ch_app, view_app, find_app
+from speclogician.presentation.preview import preview_app
+from speclogician.demos.cmd_demo import app as demo_app
+from speclogician.utils import console, require_imandra_key
+from speclogician.utils.load import load_state
+from speclogician.state.state import State
+
+
+SL_HELP : Final = """
+:robot: [bold deep_sky_blue1][italic]SpecLogician[/italic] is an AI framework for data-driven 
+formal program specification synthesis, verification, and analysis.[/bold deep_sky_blue1] :rocket:
+
+SpecLogician provides an LLM-native alternative to classical predicate abstraction and
+Counterexample-Guided Abstraction Refinement (CEGAR).
+
+Instead of requiring users or agents to discover and maintain global Boolean abstractions,
+SpecLogician models behavior directly using structured scenarios composed from state and
+action predicates. Specifications are built incrementally by defining a domain base
+(types and core invariants), predicates, transition functions, and scenarios that capture
+intent explicitly.
+
+Each change creates a new immutable state, triggers precise logical analysis, and produces
+a semantic diff against the previous state. Using ImandraX’s exact symbolic reasoning and
+region decomposition, SpecLogician computes coverage, conflicts, reachability, and
+behavioral complements—identifying real, reachable behaviors not yet explained by any
+scenario.
+
+Rather than reacting to spurious counterexamples, users and AI agents receive positive,
+actionable refinement signals in the form of uncovered or inconsistent behavioral regions.
+This enables scalable, explainable refinement toward correctness and completeness across
+source code, tests, documentation, and real-world traces—using small, explicit change
+commands instead of manual file editing.
+
+Learn more at [bold italic deep_sky_blue1]https://www.speclogician.dev![/bold italic deep_sky_blue1]
+"""
+
+app = typer.Typer(
+    name="SpecLogician",
+    help=SL_HELP,
+    rich_markup_mode="rich",
+    no_args_is_help=True
+)
+
+class AppCtx:
+    state_json_path: Path | None = None
+    state: State | None = None
+
+@app.callback()
+def _cli_entry() -> None:
+    """
+    SpecLogician CLI entry point.
+    """
+    require_imandra_key()
+
+@app.callback()
+def main(ctx: typer.Context, state_json: Path | None = typer.Option(None, "--state-json", help="...")):
+    ctx.obj = ctx.ensure_object(AppCtx)
+
+    ctx.obj.state_json_path = state_json
+
+    if state_json:
+        try:
+            ctx.obj.state = load_state(path=state_json)
+        except Exception:
+            ctx.obj.state = None
+    else:
+        ctx.obj.state = None  # ✅ ensure attribute exists
+
+app.add_typer(view_app      , name="view"       , help="View components of the state")
+app.add_typer(ch_app        , name="ch"         , help="Apply change to the state")
+app.add_typer(find_app      , name="find"       , help="Search for a components of the state")
+app.add_typer(demo_app      , name="demo"       , help="A collection of SpecLogician demos")
+app.add_typer(preview_app   , name="preview"    , hidden=True) # This is an internal tool for manually inspecting renderers
+
+
+@app.command(help="Run the TUI")
+def tui ():
+    """ Run the TUI to help us navigate and explore the state """
+    from speclogician.tui.app import SpecLogicianApp
+    tui_app = SpecLogicianApp()
+    tui_app.run()
+
+@app.command(help="Generate a prompt for helping agents use SpecLogician")
+def prompt(
+    out: Path | None = typer.Option(
+        None,
+        "--out",
+        help="Write the prompt to a file instead of stdout.",
+    ),
+):
+    """
+    Generate a prompt for helping CLI agents use SpecLogician.
+    """
+
+    here = Path(__file__).resolve()
+    repo_root = here.parents[0]
+    prompt_path = repo_root / "utils" / "prompt.md"
+
+    try:
+        txt = prompt_path.read_text()
+    except Exception as e:
+        console.print(f"🛑 Failed to read prompt file at {prompt_path}: {e}")
+        raise typer.Exit(2)
+
+    if out:
+        try:
+            out.write_text(txt)
+        except Exception as e:
+            console.print(f"🛑 Failed to write prompt to {out}: {e}")
+            raise typer.Exit(2)
+        typer.echo(str(out))
+    else:
+        typer.echo(txt)
+    
+
+@app.command()
+def version(
+    json_only: bool = typer.Option(False, "--json", help="Output JSON"),
+):
+    """Print SpecLogician version"""
+    if json_only:
+        typer.echo(f'{{"version": "{__version__}"}}')
+    else:
+        typer.echo(__version__)
+
+if __name__ == '__main__':
+    app()

speclogician/modeling/__init__.py

@@ -0,0 +1,31 @@
+#
+#   Imandra Inc.
+#
+#   speclogician/modeling/__init__.py
+#
+
+
+import re
+from typing import List
+
+IML_TYPE_REGEX = re.compile(
+    r"""
+    ^\s*type\s+                    # 'type' keyword
+    (?P<name>[a-zA-Z_][a-zA-Z0-9_]*)  # type name
+    \s*=                            # '=' sign
+    """,
+    re.MULTILINE | re.VERBOSE,
+)
+
+def strip_iml_comments(text: str) -> str:
+    """Remove OCaml-style (* ... *) and // comments."""
+    # Remove block comments
+    text = re.sub(r"\(\*.*?\*\)", "", text, flags=re.DOTALL)
+    # Remove line comments
+    text = re.sub(r"//.*", "", text)
+    return text
+
+def extract_declared_types(iml_text: str) -> List[str]:
+    """Return all declared type names in an IML file."""
+    clean = strip_iml_comments(iml_text)
+    return [m.group("name") for m in IML_TYPE_REGEX.finditer(clean)]

speclogician/modeling/complement.py

@@ -0,0 +1,104 @@
+#
+#   Imandra Inc.
+#
+#   speclogician/modeling/complement.py
+#
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Sequence, Iterable
+
+from pydantic import BaseModel
+from imandrax_api_models import RegionStr
+
+
+class ScenarioComplement(BaseModel):
+    """Result of running region decomposition on all the combined scenarios."""
+    regions: Sequence[RegionStr]
+
+
+class ScenarioComplementDiff(BaseModel):
+    """
+    Difference between two scenario complements (before -> after),
+    computed using stable fingerprints of regions.
+
+    We store only fingerprints by default (regions can be huge).
+    """
+    num_regions_before: int
+    num_regions_after: int
+    regions_added: list[str]      # fingerprints that appear in after but not before
+    regions_removed: list[str]    # fingerprints that appear in before but not after
+
+
+def _canon_region_str(r: RegionStr) -> str:
+    """
+    Produce a deterministic string representation of a RegionStr.
+
+    We prefer a canonical JSON-ish blob rather than str(r) because:
+      - __repr__ / __str__ may change
+      - dict ordering may vary
+    """
+    # constraints_str is typically a list of strings
+    constraints = list(getattr(r, "constraints_str", []) or [])
+
+    invariant = getattr(r, "invariant_str", "") or ""
+    model_eval = getattr(r, "model_eval_str", "") or ""
+
+    # model_str can be dict-like (often {'s': '{x = 0}'}). Canonicalize ordering.
+    model = getattr(r, "model_str", None)
+    if isinstance(model, dict):
+        # stringify values to avoid non-jsonable shapes
+        model_items = {str(k): str(v) for k, v in sorted(model.items(), key=lambda kv: str(kv[0]))}
+    elif model is None:
+        model_items = {}
+    else:
+        # fallback: stringify
+        model_items = {"_": str(model)}
+
+    payload = {
+        "constraints": constraints,
+        "invariant": invariant,
+        "model": model_items,
+        "model_eval": model_eval,
+    }
+
+    # separators for stable compact encoding
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"))
+
+
+def _fingerprint_region(r: RegionStr | str) -> str:
+    """
+    Stable-ish fingerprint for a RegionStr (or a raw string region).
+    """
+    if isinstance(r, RegionStr):
+        s = _canon_region_str(r)
+    else:
+        s = str(r)
+
+    h = hashlib.sha256(s.encode("utf-8")).hexdigest()
+    # short prefix is plenty for diffs + UI, but keep full if you prefer
+    return h[:16]
+
+
+def _fingerprints(regions: Iterable[RegionStr | str]) -> set[str]:
+    return {_fingerprint_region(r) for r in regions}
+
+
+def diff_scenario_complement(before: ScenarioComplement, after: ScenarioComplement) -> ScenarioComplementDiff:
+    before_regions = list(before.regions or [])
+    after_regions = list(after.regions or [])
+
+    bf = _fingerprints(before_regions)
+    af = _fingerprints(after_regions)
+
+    added = sorted(list(af - bf))
+    removed = sorted(list(bf - af))
+
+    return ScenarioComplementDiff(
+        num_regions_before=len(before_regions),
+        num_regions_after=len(after_regions),
+        regions_added=added,
+        regions_removed=removed,
+    )

speclogician/modeling/component.py

@@ -0,0 +1,71 @@
+#
+#   Imandra Inc.
+#
+#   speclogician/modeling/component.py
+#
+
+import uuid
+import re
+from datetime import datetime, timezone
+from pydantic import BaseModel, Field, field_validator, ConfigDict
+from ..utils import IMLValidity
+
+_NAME_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+
+# Conservative reserved set (OCaml-ish + common IML surface syntax).
+# Add more as you run into them.
+_IML_RESERVED: set[str] = {
+    # core keywords / syntax
+    "let", "in", "and", "rec",
+    "type", "match", "with", "function",
+    "if", "then", "else",
+    "try", "raise",
+    "module", "open", "include",
+    "begin", "end",
+    "as", "of", "when",
+
+    # booleans / common literals
+    "true", "false",
+
+    # common types / constructors that are often special-cased
+    "some", "none",
+}
+
+def validate_iml_identifier(name: str) -> str:
+    if not _NAME_RE.fullmatch(name):
+        raise ValueError(
+            f"Invalid name '{name}'. Must start with a lowercase letter and contain only "
+            "lowercase letters, digits, and underscores."
+        )
+    if name in _IML_RESERVED:
+        raise ValueError(f"Invalid name '{name}': reserved keyword in IML/OCaml surface syntax.")
+    return name
+
+class ModelComponent(BaseModel):
+    """
+    Base class for all model components (Predicates, transitions and scenarios)
+    """
+    model_config = ConfigDict(validate_assignment=True)  # optional but recommended
+
+    comp_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    name: str
+
+    # Track last update time (UTC)
+    last_updated: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        return validate_iml_identifier(v)
+
+    def touch(self) -> None:
+        self.last_updated = datetime.now(timezone.utc)
+    
+class SrcComponent(ModelComponent):
+    src_code: str = ""
+    is_iml_valid : IMLValidity = IMLValidity.UNKNOWN
+    iml_error: str | None = None
+
+    def set_src_code(self, src_code: str) -> None:
+        self.src_code = src_code
+        self.touch()

speclogician/modeling/conflict.py

@@ -0,0 +1,26 @@
+#
+#   Imandra Inc.    
+#
+#   speclogician/modeling/conflict.py
+#
+
+from pydantic import BaseModel
+from typing import Literal, TypeAlias
+
+class ScenarioOverlap(BaseModel):
+    """ Two scenarios overlap in constraints """
+    kind: Literal["overlap"] = "overlap"
+    scenario_name1 : str
+    scenario_name2 : str
+
+    details : str
+
+class ScenarioConsumed(BaseModel):
+    """ One scenario fully absorbs another """
+    kind: Literal["consumed"] = "consumed"
+    scenario_name1 : str
+    scenario_name2 : str
+
+    details : str
+
+ScenarioConflict : TypeAlias = ScenarioOverlap | ScenarioConsumed