Metadata-Version: 2.3
Name: speclogician
Version: 1.0.1
Summary: SpecLogician AI framework for data-driven formal program specification synthesis, verification and analysis
Author: denis, hongyu
Author-email: denis <denis@imandra.ai>, hongyu <hongyu@imandra.ai>
Requires-Dist: imandrax-api-models>=18.0.0
Requires-Dist: iml-query>=0.5.1
Requires-Dist: pydantic>=2.12.5
Requires-Dist: rich>=14.2.0
Requires-Dist: textual>=6.11.0
Requires-Dist: typer>=0.20.0
Requires-Python: >=3.12
Project-URL: Homepage, https://speclogician.dev/
Description-Content-Type: text/markdown

# SpecLogician
SpecLogician AI framework for data-driven formal program specification synthesis, verification and analysis

www.speclogician.dev

## 1) The challenge: scaling formal methods via LLM-powered automation

- Automatically applying formal methods to large software systems using **LLM-powered and agentic tools** remains a fundamental challenge
- Traditional formal modeling approaches require building **large, monolithic formal models upfront**
- There is **no single canonical way** to formalize a complex software system
- As a result, formalization becomes **as much an art as a science**, relying heavily on expert judgment
- These characteristics fundamentally limit automation:
  - LLMs struggle to generate or maintain **large, globally consistent formal models**
  - Small local changes often require understanding the entire model
  - Monolithic models are brittle under iterative, agent-driven workflows


## 2) SpecLogician’s core idea

- SpecLogician is an **AI framework for data-driven formal program specification synthesis, verification, and analysis**
- It replaces monolithic specifications with **incrementally constructed formal logic**
- The core logic is built from **symbolic `given / when / then` scenarios**
- Scenarios are:
  - composable
  - declarative
  - local in scope
- Scenarios are connected to a **domain model of arbitrary complexity**
- The domain model captures:
  - predicates
  - transitions
  - state/action structure
  - auxiliary and domain-specific logic


## 3) Why this structure works well with LLMs

- LLM-powered tools are used to:
  - propose new scenarios
  - refine existing scenarios
  - generate structured deltas (add / remove / edit)
- LLMs operate on **small, well-scoped artifacts**, not entire formal models
- Each change is:
  - explicit
  - typed
  - machine-checkable
- This aligns naturally with how LLMs perform best:
  - local reasoning
  - incremental edits
  - structured outputs (JSON, CLI commands)


## 4) Agentic reasoning loop (formal reasoning as the backbone)

- SpecLogician sits at the center of an **agentic reasoning loop**
- In this loop:
  - **CodeLogician / ImandraX** translate source code into formal models and reasoning artifacts
  - **LLM-powered agentic CLIs** propose scenario additions, edits, and removals as structured deltas
  - **Software mapping tools** (e.g. CodeMaps from cognition.ai) provide high-level program structure and navigation context
- Each agent contributes **partial, local insight**:
  - code structure
  - behavioral intent
  - execution traces
  - test artifacts
- SpecLogician:
  - integrates these inputs into a single formal state
  - validates them symbolically
  - delegates global analysis to the **ImandraX automated reasoning engine**
- The reasoning engine analyzes the **entire accumulated model after every change**
- This creates a **closed-loop workflow**:
  - propose → formalize → verify → refine


## 5) What the resulting formal model enables

- Systematically identify **gaps in design and requirements**
- Precisely understand **test coverage and gaps in test coverage**
- Trace:
  - execution logs
  - test cases
  - documentation
  - other artifacts  
  back to **formal specifications and requirements**
- Automatically **generate missing test cases**
- Safely **model and verify the impact of changes** before they are applied
- Maintain a **single, authoritative source of truth** for system behavior


## 6) Big-picture outcome

- Transforms LLMs from:
  - probabilistic code generators  
  into:
  - **reliable collaborators in a verification-driven workflow**
- Makes formal methods:
  - incremental
  - data-driven
  - compatible with LLM-powered automation
  - scalable to real-world software systems
- Positions SpecLogician as the **formal reasoning backbone** for modern, agentic software development

