cortex-solver 3.0.0__py3-none-any.whl

cortex/tools/validate.py

@@ -0,0 +1,75 @@
+"""Tool handler for the ``validate`` MCP tool."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cortex.core.validator import validate
+from cortex.types import (
+    Constraint,
+    Dimensions,
+    Mirror,
+    PartRecipe,
+    PartSpec,
+    _to_dict,
+)
+
+
+def _parse_recipe(raw: dict[str, Any]) -> PartRecipe:
+    """Convert a raw JSON dict into a typed PartRecipe."""
+    parts: dict[str, PartSpec] = {}
+    for name, spec in raw.get("parts", {}).items():
+        dims = spec.get("dimensions", {})
+        parts[name] = PartSpec(
+            name=name,
+            dimensions=Dimensions(
+                width=float(dims.get("w", dims.get("width", 0))),
+                depth=float(dims.get("d", dims.get("depth", 0))),
+                height=float(dims.get("h", dims.get("height", 0))),
+            ),
+            type=spec.get("type", ""),
+            params=spec.get("params", {}),
+            metadata=spec.get("metadata", {}),
+        )
+
+    constraints: list[Constraint] = []
+    for c in raw.get("constraints", []):
+        constraints.append(
+            Constraint(
+                type=c["type"],
+                part_a=c["part_a"],
+                part_b=c["part_b"],
+                axis=c.get("axis", ""),
+                face_a=c.get("face_a", ""),
+                face_b=c.get("face_b", ""),
+                offset=float(c.get("offset", 0)),
+                reference=c.get("reference", ""),
+            )
+        )
+
+    mirrors: list[Mirror] = []
+    for m in raw.get("mirrors", []):
+        mirrors.append(
+            Mirror(
+                source=m["source"],
+                target=m["target"],
+                axis=m["axis"],
+            )
+        )
+
+    return PartRecipe(
+        name=raw.get("name", ""),
+        anchor=raw.get("anchor", ""),
+        anchor_position=[float(v) for v in raw.get("anchor_position", [0, 0, 0])],
+        parts=parts,
+        constraints=constraints,
+        mirrors=mirrors,
+        collections=raw.get("collections", {}),
+    )
+
+
+def handle_validate(arguments: dict[str, Any]) -> dict[str, Any]:
+    """Parse input and delegate to the validator."""
+    recipe = _parse_recipe(arguments["recipe"])
+    result = validate(recipe)
+    return _to_dict(result)

cortex/tools/verify.py

@@ -0,0 +1,22 @@
+"""Tool handler for the ``verify`` MCP tool."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cortex.core.verifier import verify
+from cortex.types import _to_dict
+
+
+def handle_verify(arguments: dict[str, Any]) -> dict[str, Any]:
+    """Parse input and delegate to the verifier."""
+    object_name: str = arguments["object_name"]
+    object_data: dict = arguments["object_data"]
+    expected: dict = arguments["expected"]
+
+    result = verify(
+        object_name=object_name,
+        object_data=object_data,
+        expected=expected,
+    )
+    return _to_dict(result)

cortex/types.py

@@ -0,0 +1,298 @@
+"""Cortex type definitions — all dataclasses for the MCP build-methodology server."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, fields as _dc_fields
+from enum import Enum
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+
+class ConstraintType(str, Enum):
+    """Part-level constraint types."""
+
+    STACKED = "STACKED"
+    CENTERED = "CENTERED"
+    FLUSH = "FLUSH"
+    OFFSET = "OFFSET"
+    COAXIAL = "COAXIAL"
+    INSIDE = "INSIDE"
+    ALIGNED = "ALIGNED"
+    SYMMETRIC = "SYMMETRIC"
+
+
+class SceneConstraintType(str, Enum):
+    """Scene-level constraint types."""
+
+    GRID = "GRID"
+    ALONG_PATH = "ALONG_PATH"
+    RADIAL = "RADIAL"
+    FACING = "FACING"
+    DISTANCE = "DISTANCE"
+    AGAINST_EDGE = "AGAINST_EDGE"
+    RANDOM_SCATTER = "RANDOM_SCATTER"
+    STACK_VERTICAL = "STACK_VERTICAL"
+    MIRROR_SCENE = "MIRROR_SCENE"
+
+
+class Scope(str, Enum):
+    OBJECT = "object"
+    SCENE = "scene"
+
+
+class DetailLevel(str, Enum):
+    BASIC = "basic"
+    DETAILED = "detailed"
+    EXHAUSTIVE = "exhaustive"
+
+
+class Severity(str, Enum):
+    CRITICAL = "critical"
+    WARNING = "warning"
+    INFO = "info"
+
+
+# ---------------------------------------------------------------------------
+# Core geometry
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class Dimensions:
+    """Width (X), depth (Y), height (Z)."""
+
+    width: float
+    depth: float
+    height: float
+
+    def as_list(self) -> list[float]:
+        return [self.width, self.depth, self.height]
+
+
+# ---------------------------------------------------------------------------
+# Part recipe types
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class PartSpec:
+    """Specification for a single part."""
+
+    name: str
+    dimensions: Dimensions
+    type: str = ""
+    params: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class Constraint:
+    """A single constraint between two parts."""
+
+    type: str
+    part_a: str
+    part_b: str
+    axis: str
+    face_a: str = ""
+    face_b: str = ""
+    offset: float = 0.0
+    reference: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class Mirror:
+    """Mirror definition — clone *source* to *target* across *axis*."""
+
+    source: str
+    target: str
+    axis: str
+
+
+@dataclass(slots=True)
+class PartRecipe:
+    """Full recipe describing an object's parts and their relationships."""
+
+    name: str
+    anchor: str
+    anchor_position: list[float]
+    parts: dict[str, PartSpec]
+    constraints: list[Constraint]
+    mirrors: list[Mirror] = field(default_factory=list)
+    collections: dict[str, list[str]] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Scene recipe types
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class SceneConstraint:
+    """A single scene-level constraint."""
+
+    type: str
+    object: str | list[str]
+    params: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class SceneRecipe:
+    """Full recipe describing a scene layout."""
+
+    name: str
+    bounds: dict[str, list[float]]
+    objects: dict[str, PartSpec]
+    zones: dict[str, Any] = field(default_factory=dict)
+    constraints: list[SceneConstraint] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Result types
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class SolveResult:
+    """Result of constraint solving."""
+
+    success: bool
+    positions: dict[str, dict[str, list[float]]] = field(default_factory=dict)
+    build_order: list[str] = field(default_factory=list)
+    conflicts: list[dict[str, Any]] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    error: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class VerifyCheck:
+    """Result of a single verification check."""
+
+    name: str
+    passed: bool
+    details: str
+    severity: str
+
+
+@dataclass(slots=True)
+class VerifyResult:
+    """Aggregated verification result for one object."""
+
+    object_name: str
+    passed: bool
+    checks: list[VerifyCheck]
+    summary: str
+
+
+# ---------------------------------------------------------------------------
+# Decomposition result types
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class HierarchyNode:
+    """Single node in a decomposition hierarchy."""
+
+    name: str
+    parent: str | None = None
+    connection: str = ""
+    children: list[str] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class ResearchItem:
+    """What research is needed for a specific part."""
+
+    part: str
+    needed: list[str] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class DecomposeResult:
+    """Full output from the decompose tool."""
+
+    subject: str
+    hierarchy: dict[str, HierarchyNode]
+    research_required: list[ResearchItem]
+    total_parts: int
+    build_order: list[str]
+
+
+@dataclass(slots=True)
+class ResearchWarning:
+    """Warning about a researched value."""
+
+    part: str
+    field: str
+    value: Any
+    concern: str
+
+
+@dataclass(slots=True)
+class MissingField:
+    """A missing research field."""
+
+    part: str
+    field: str
+    hint: str = ""
+
+
+@dataclass(slots=True)
+class ResearchResult:
+    """Full output from the research tool."""
+
+    complete: bool
+    missing: list[MissingField]
+    warnings: list[ResearchWarning]
+    ready_for_recipe: bool
+
+
+@dataclass(slots=True)
+class ValidationError:
+    """A single validation error."""
+
+    type: str
+    message: str
+    location: str = ""
+
+
+@dataclass(slots=True)
+class ValidationWarning:
+    """A single validation warning."""
+
+    type: str
+    message: str
+
+
+@dataclass(slots=True)
+class ValidationResult:
+    """Full output from the validate tool."""
+
+    valid: bool
+    errors: list[ValidationError]
+    warnings: list[ValidationWarning]
+
+
+# ---------------------------------------------------------------------------
+# Serialisation helpers
+# ---------------------------------------------------------------------------
+
+
+def _to_dict(obj: Any) -> Any:
+    """Recursively convert dataclasses / enums to plain dicts for JSON."""
+    if isinstance(obj, dict):
+        return {k: _to_dict(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_to_dict(v) for v in obj]
+    if isinstance(obj, Enum):
+        return obj.value
+    if hasattr(obj, "__dataclass_fields__"):
+        return {
+            f.name: _to_dict(getattr(obj, f.name))
+            for f in _dc_fields(obj)
+            if not f.name.startswith("_")
+        }
+    return obj

cortex_solver-3.0.0.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: cortex-solver
+Version: 3.0.0
+Summary: MCP server that enforces build methodology for LLMs
+Project-URL: Homepage, https://github.com/cortex-solver/cortex
+License-Expression: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: mcp
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cortex-solver
+
+cortex-solver is an MCP server that enforces a rigorous build methodology for LLMs constructing 3D objects and scenes. It provides a structured pipeline to decompose subjects, validate research, solve geometric constraints, and verify the final output.
+
+## Installation
+
+Run directly using uvx:
+
+```bash
+uvx cortex-solver
+```
+
+Or install permanently:
+
+```bash
+uv pip install cortex-solver
+```
+
+## MCP Configuration
+
+To use cortex-solver with an MCP client, add it to your configuration file:
+
+```json
+{
+  "mcpServers": {
+    "cortex": {
+      "command": "uvx",
+      "args": ["cortex-solver"]
+    }
+  }
+}
+```
+
+## Build Pipeline
+
+The server enforces a linear workflow for constructing 3D objects:
+
+1. Decompose: Break the subject into a part hierarchy.
+2. Research: Validate that all necessary research data is present.
+3. Validate: Check the structural integrity and logic of the recipe.
+4. Solve: Compute precise 3D positions based on constraints.
+5. Verify: Confirm the built object matches the solver output.
+6. Solve Scene: Arrange multiple objects within a larger scene.
+
+## Tools
+
+### decompose
+Breaks a subject into a hierarchical part/object tree and generates research checklists.
+- subject (string): The name of the object to decompose.
+- variant (string, optional): Specific version or style of the subject.
+- scope (string, optional): Scope of the decomposition.
+- detail_level (string, optional): Level of granularity for the hierarchy.
+
+### research
+Validates the completeness of research data and identifies missing information.
+- hierarchy (object): The part hierarchy from the decompose tool.
+- filled_data (object, optional): The current research data to validate.
+
+### validate
+Checks the recipe schema, references, cycles, and constraint validity.
+- recipe (object): The complete build recipe for the object.
+
+### solve
+Computes part positions via constraint resolution. Returns positions, build order, and any conflicts.
+- recipe (object): The validated build recipe.
+
+### solve_scene
+Computes placements for multiple objects in a scene. Returns positions, rotations, and scales.
+- scene_recipe (object): The recipe defining the scene and its constraints.
+
+### verify
+Verifies a built object against the solver output, checking mesh health, transforms, and dimensions.
+- object_name (string): Name of the object to verify.
+- object_data (object): Data from the constructed object.
+- expected (object): The expected values from the solver.
+
+## Constraints
+
+### Part Constraints
+Used during the object build phase:
+- STACKED
+- CENTERED
+- FLUSH
+- OFFSET
+- COAXIAL
+- INSIDE
+- ALIGNED
+- SYMMETRIC
+
+### Scene Constraints
+Used during the scene arrangement phase:
+- GRID
+- ALONG_PATH
+- RADIAL
+- FACING
+- DISTANCE
+- AGAINST_EDGE
+- RANDOM_SCATTER
+- STACK_VERTICAL
+- MIRROR_SCENE
+
+## Project Structure
+
+```
+cortex/
+├── __init__.py
+├── __main__.py
+├── server.py
+├── types.py
+├── core/
+│   ├── solver.py
+│   ├── scene_solver.py
+│   ├── validator.py
+│   ├── verifier.py
+│   └── decomposer.py
+└── tools/
+    ├── decompose.py
+    ├── research.py
+    ├── validate.py
+    ├── solve.py
+    ├── solve_scene.py
+    └── verify.py
+```
+
+## Development
+
+Set up the environment and run tests:
+
+```bash
+uv sync --extra dev
+uv run pytest
+```
+
+## License
+
+MIT

cortex_solver-3.0.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+cortex/__init__.py,sha256=nEbnd_yPvQp6Mgt16N3_1BX4ZCOVkG-qUSIvD8y5DTY,99
+cortex/__main__.py,sha256=Y6wNGY4NPx70Xw8JSO3vAsnj6qbSox0iBdvKXlwwk9w,85
+cortex/server.py,sha256=LJcXxqVxUOElLzBtrymq9NF58eTNi5FDpfSczqM3aSg,7169
+cortex/types.py,sha256=THPjCYk2h6ALRd8Go6XB3mJpfglK5h7QZIlzWRARE_E,7021
+cortex/core/__init__.py,sha256=qttevc6amsmADPmQHQw8r_nWWsdpgXaD2uxJKYNjUZ8,38
+cortex/core/decomposer.py,sha256=WEhkDgDyn4Yw9U7_t0Kl6KxlRRJ51gdyWrc5DAcy7oc,31985
+cortex/core/scene_solver.py,sha256=CGs-vBotp609o2QBdv71njmCJI-naTUWNUTYHoXSmPU,18009
+cortex/core/solver.py,sha256=ZBxA-PTNLCqb7_pFjHpAiaekQ2ibRpzByNAYj9XqSJs,9555
+cortex/core/validator.py,sha256=Q0-IDQHAr6DfnYmAtoyCgYEOCi0MZo-sSqJwRyHuJts,12907
+cortex/core/verifier.py,sha256=nTpUTJl82O4Ykm_Z59sg3yhJfin_ivcMwUhwK56Wjw8,9943
+cortex/tools/__init__.py,sha256=16IN7VHvXL3Ityxe9rLnaldLd9qI3ccYGGf1fyG-fJM,36
+cortex/tools/decompose.py,sha256=_ImuASejK2PKdQVACbkUbEQbBrSEHRzEoqI5_6BCugc,683
+cortex/tools/research.py,sha256=3vayN8JqQK8MDkHlIirip9zq10qn0Ms7E66PJkh2my4,519
+cortex/tools/solve.py,sha256=4mx2gKk7VcwvEXYyQbcn8be7xz0OkFLy3-35pP-DmsA,445
+cortex/tools/solve_scene.py,sha256=h6V15Cv5Gp9rrMiuXg-coHEg1kcgMLofwE1ABZoNM2M,1764
+cortex/tools/validate.py,sha256=V7nuJKMPE_Lfw5c0m3X7oos72EX4mdLkYF5D2CcWnTM,2229
+cortex/tools/verify.py,sha256=UZ_tpz3apgFRwkgUTqZRj7lhxvNnCCCvs8-fV44JXLk,590
+cortex_solver-3.0.0.dist-info/METADATA,sha256=qN6JcVbTqJSZcmJH3m9oflrcC7oPV7l8_3kPvhi8sLM,3873
+cortex_solver-3.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+cortex_solver-3.0.0.dist-info/entry_points.txt,sha256=VJ_FWlfV87S0FVdYs11osG4CZsLYfCbUpHrGkkyJLZg,39
+cortex_solver-3.0.0.dist-info/RECORD,,

cortex_solver-3.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cortex_solver-3.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cortex = cortex:main