cortex-solver 3.0.0__py3-none-any.whl

cortex/core/verifier.py

@@ -0,0 +1,307 @@
+"""Post-build verification for 3D objects."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+from cortex.types import VerifyCheck, VerifyResult
+
+
+@dataclass(frozen=True, slots=True)
+class AxisDeviation:
+    axis: str
+    actual: float
+    expected: float
+    delta: float
+
+
+def _get_list(value: object, length: int) -> list[float] | None:
+    if not isinstance(value, (list, tuple)):
+        return None
+    if len(value) != length:
+        return None
+    try:
+        return [float(item) for item in value]
+    except (TypeError, ValueError):
+        return None
+
+
+def _axis_deviations(
+    actual: list[float], expected: list[float], axes: Iterable[str]
+) -> list[AxisDeviation]:
+    deviations: list[AxisDeviation] = []
+    for axis, actual_value, expected_value in zip(axes, actual, expected):
+        delta = actual_value - expected_value
+        deviations.append(
+            AxisDeviation(
+                axis=axis,
+                actual=actual_value,
+                expected=expected_value,
+                delta=delta,
+            )
+        )
+    return deviations
+
+
+def _format_axis_details(
+    label: str, deviations: list[AxisDeviation], tolerance: float
+) -> str:
+    failures = []
+    for deviation in deviations:
+        if abs(deviation.delta) > tolerance:
+            failures.append(
+                f"{label}.{deviation.axis}: actual={deviation.actual:.4f}, "
+                f"expected={deviation.expected:.4f}, delta={deviation.delta:.4f}"
+            )
+    if not failures:
+        return f"{label} within tolerance"
+    return "; ".join(failures)
+
+
+def _missing_details(field: str) -> str:
+    return f"Missing required field: {field}"
+
+
+def _mesh_health_check(object_data: dict) -> VerifyCheck:
+    missing_fields = [
+        name
+        for name in (
+            "has_ngons",
+            "has_non_manifold",
+            "has_loose_vertices",
+            "normals_consistent",
+        )
+        if name not in object_data
+    ]
+    if missing_fields:
+        details = "; ".join(_missing_details(name) for name in missing_fields)
+        return VerifyCheck(
+            name="mesh_health",
+            passed=False,
+            details=details,
+            severity="critical",
+        )
+
+    has_non_manifold = bool(object_data.get("has_non_manifold"))
+    warnings = []
+    if object_data.get("has_ngons"):
+        warnings.append("Object has N-gons")
+    if object_data.get("has_loose_vertices"):
+        warnings.append("Loose vertices found")
+    if not object_data.get("normals_consistent"):
+        warnings.append("Inconsistent normals")
+    if has_non_manifold:
+        warnings.append("Non-manifold geometry detected")
+
+    passed = not has_non_manifold
+    details = "OK" if not warnings else "; ".join(warnings)
+    return VerifyCheck(
+        name="mesh_health",
+        passed=passed,
+        details=details,
+        severity="critical",
+    )
+
+
+def _identity_check(object_data: dict, expected: dict) -> VerifyCheck:
+    scale = _get_list(object_data.get("scale"), 3)
+    if scale is None:
+        return VerifyCheck(
+            name="identity",
+            passed=False,
+            details=_missing_details("scale"),
+            severity="critical",
+        )
+
+    expected_collection = expected.get("collection")
+    actual_collection = object_data.get("collection")
+    if expected_collection is not None and actual_collection is None:
+        return VerifyCheck(
+            name="identity",
+            passed=False,
+            details=_missing_details("collection"),
+            severity="critical",
+        )
+
+    tolerance = 0.001
+    scale_ok = all(abs(value - 1.0) <= tolerance for value in scale)
+    collection_ok = (
+        expected_collection is None or actual_collection == expected_collection
+    )
+
+    failures = []
+    if not scale_ok:
+        deviations = _axis_deviations(scale, [1.0, 1.0, 1.0], ("x", "y", "z"))
+        failures.append(_format_axis_details("scale", deviations, tolerance))
+    if not collection_ok:
+        failures.append(
+            f"collection mismatch: actual={actual_collection!r}, expected={expected_collection!r}"
+        )
+
+    passed = scale_ok and collection_ok
+    details = "OK" if passed else "; ".join(failures)
+    return VerifyCheck(
+        name="identity",
+        passed=passed,
+        details=details,
+        severity="critical",
+    )
+
+
+def _placement_check(object_data: dict, expected: dict) -> VerifyCheck:
+    actual_location = _get_list(object_data.get("location"), 3)
+    expected_location = _get_list(expected.get("location"), 3)
+    if actual_location is None:
+        return VerifyCheck(
+            name="placement",
+            passed=False,
+            details=_missing_details("location"),
+            severity="critical",
+        )
+    if expected_location is None:
+        return VerifyCheck(
+            name="placement",
+            passed=False,
+            details=_missing_details("expected.location"),
+            severity="critical",
+        )
+
+    tolerance = 0.001
+    deviations = _axis_deviations(actual_location, expected_location, ("x", "y", "z"))
+    passed = all(abs(dev.delta) <= tolerance for dev in deviations)
+    details = _format_axis_details("location", deviations, tolerance)
+    return VerifyCheck(
+        name="placement",
+        passed=passed,
+        details=details,
+        severity="critical",
+    )
+
+
+def _neighbors_lookup(neighbors: object) -> dict[str, dict]:
+    if not isinstance(neighbors, list):
+        return {}
+    lookup: dict[str, dict] = {}
+    for neighbor in neighbors:
+        if isinstance(neighbor, dict) and "name" in neighbor:
+            lookup[str(neighbor["name"])] = neighbor
+    return lookup
+
+
+def _connection_check(object_data: dict, expected: dict) -> VerifyCheck:
+    expected_neighbors = expected.get("neighbors")
+    if expected_neighbors is None:
+        return VerifyCheck(
+            name="connection",
+            passed=True,
+            details="No neighbor expectations",
+            severity="warning",
+        )
+    if not isinstance(expected_neighbors, list):
+        return VerifyCheck(
+            name="connection",
+            passed=False,
+            details=_missing_details("expected.neighbors"),
+            severity="warning",
+        )
+
+    actual_lookup = _neighbors_lookup(object_data.get("neighbors"))
+    tolerance = 0.002
+    failures: list[str] = []
+    for neighbor in expected_neighbors:
+        if not isinstance(neighbor, dict) or "name" not in neighbor:
+            failures.append("Invalid expected neighbor entry")
+            continue
+        name = str(neighbor.get("name"))
+        expected_distance = neighbor.get("min_distance")
+        if expected_distance is None:
+            failures.append(f"Missing expected min_distance for {name}")
+            continue
+        actual_neighbor = actual_lookup.get(name)
+        if actual_neighbor is None:
+            failures.append(f"Missing neighbor: {name}")
+            continue
+        actual_distance = actual_neighbor.get("closest_distance")
+        if actual_distance is None:
+            failures.append(f"Missing closest_distance for {name}")
+            continue
+        try:
+            actual_distance_value = float(actual_distance)
+            expected_distance_value = float(expected_distance)
+        except (TypeError, ValueError):
+            failures.append(f"Invalid distance data for {name}")
+            continue
+        delta = actual_distance_value - expected_distance_value
+        if abs(delta) > tolerance:
+            failures.append(
+                f"{name}: actual={actual_distance_value:.4f}, expected={expected_distance_value:.4f}, "
+                f"delta={delta:.4f}"
+            )
+
+    passed = not failures
+    details = "All connections within tolerance" if passed else "; ".join(failures)
+    return VerifyCheck(
+        name="connection",
+        passed=passed,
+        details=details,
+        severity="warning",
+    )
+
+
+def _dimensions_check(object_data: dict, expected: dict) -> VerifyCheck:
+    actual_dimensions = _get_list(object_data.get("dimensions"), 3)
+    expected_dimensions = _get_list(expected.get("dimensions"), 3)
+    if actual_dimensions is None:
+        return VerifyCheck(
+            name="dimensions",
+            passed=False,
+            details=_missing_details("dimensions"),
+            severity="warning",
+        )
+    if expected_dimensions is None:
+        return VerifyCheck(
+            name="dimensions",
+            passed=False,
+            details=_missing_details("expected.dimensions"),
+            severity="warning",
+        )
+
+    tolerance = 0.005
+    deviations = _axis_deviations(
+        actual_dimensions, expected_dimensions, ("x", "y", "z")
+    )
+    passed = all(abs(dev.delta) <= tolerance for dev in deviations)
+    details = _format_axis_details("dimensions", deviations, tolerance)
+    return VerifyCheck(
+        name="dimensions",
+        passed=passed,
+        details=details,
+        severity="warning",
+    )
+
+
+def _summarize(checks: list[VerifyCheck]) -> str:
+    failed = [check.name for check in checks if not check.passed]
+    if not failed:
+        return "All checks passed"
+    return f"{len(failed)} of {len(checks)} checks failed: {', '.join(failed)}"
+
+
+def verify(object_name: str, object_data: dict, expected: dict) -> VerifyResult:
+    """Verify a post-build object against expected values."""
+    checks = [
+        _mesh_health_check(object_data),
+        _identity_check(object_data, expected),
+        _placement_check(object_data, expected),
+        _connection_check(object_data, expected),
+        _dimensions_check(object_data, expected),
+    ]
+    passed = all(check.passed for check in checks if check.severity == "critical")
+    summary = _summarize(checks)
+    return VerifyResult(
+        object_name=object_name,
+        passed=passed,
+        checks=checks,
+        summary=summary,
+    )

cortex/server.py

@@ -0,0 +1,226 @@
+"""Cortex MCP server — tool registration and stdio transport."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+
+from cortex.tools.decompose import handle_decompose
+from cortex.tools.research import handle_research
+from cortex.tools.validate import handle_validate
+from cortex.tools.solve import handle_solve
+from cortex.tools.solve_scene import handle_solve_scene
+from cortex.tools.verify import handle_verify
+
+# ---------------------------------------------------------------------------
+# Server instance
+# ---------------------------------------------------------------------------
+
+server = Server("cortex")
+
+# ---------------------------------------------------------------------------
+# Tool definitions
+# ---------------------------------------------------------------------------
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="decompose",
+        description=(
+            "Decompose a subject into a hierarchical part/object tree with "
+            "research checklists. First step in the build pipeline."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "subject": {
+                    "type": "string",
+                    "description": "The object or scene to decompose (e.g. 'office chair', 'city block').",
+                },
+                "variant": {
+                    "type": "string",
+                    "description": "Optional variant (e.g. 'gaming', 'modern').",
+                    "default": "",
+                },
+                "scope": {
+                    "type": "string",
+                    "enum": ["object", "scene"],
+                    "description": "Whether to decompose as a single object or a scene of objects.",
+                    "default": "object",
+                },
+                "detail_level": {
+                    "type": "string",
+                    "enum": ["basic", "detailed", "exhaustive"],
+                    "description": "How deep to decompose.",
+                    "default": "detailed",
+                },
+            },
+            "required": ["subject"],
+        },
+    ),
+    Tool(
+        name="research",
+        description=(
+            "Validate research data completeness and sanity-check dimensions. "
+            "Tells the LLM what data is still missing before recipe creation."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "hierarchy": {
+                    "type": "object",
+                    "description": "Hierarchy from decompose output.",
+                },
+                "filled_data": {
+                    "type": "object",
+                    "description": "Partial research data: {part_name: {dimensions: {w,d,h}, ...}}.",
+                    "default": None,
+                },
+            },
+            "required": ["hierarchy"],
+        },
+    ),
+    Tool(
+        name="validate",
+        description=(
+            "Validate a part recipe for structural correctness before solving. "
+            "Checks schema, references, cycles, and constraint validity."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "recipe": {
+                    "type": "object",
+                    "description": "The part recipe to validate.",
+                },
+            },
+            "required": ["recipe"],
+        },
+    ),
+    Tool(
+        name="solve",
+        description=(
+            "Solve part positions from a validated recipe using constraint resolution. "
+            "Returns absolute positions, build order, and any conflicts."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "recipe": {
+                    "type": "object",
+                    "description": "A validated part recipe.",
+                },
+            },
+            "required": ["recipe"],
+        },
+    ),
+    Tool(
+        name="solve_scene",
+        description=(
+            "Solve object placements in a scene from scene-level constraints. "
+            "Returns positions, rotations, and scales for each object."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_recipe": {
+                    "type": "object",
+                    "description": "A scene recipe with objects, zones, and constraints.",
+                },
+            },
+            "required": ["scene_recipe"],
+        },
+    ),
+    Tool(
+        name="verify",
+        description=(
+            "Verify a built object against expected solver output. "
+            "Checks mesh health, transforms, placement, connections, and dimensions."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "object_name": {
+                    "type": "string",
+                    "description": "Name of the object to verify.",
+                },
+                "object_data": {
+                    "type": "object",
+                    "description": "Actual measured data from the 3D engine.",
+                },
+                "expected": {
+                    "type": "object",
+                    "description": "Expected values from solver output.",
+                },
+            },
+            "required": ["object_name", "object_data", "expected"],
+        },
+    ),
+]
+
+
+# ---------------------------------------------------------------------------
+# Handlers
+# ---------------------------------------------------------------------------
+
+
+@server.list_tools()
+async def list_tools() -> list[Tool]:
+    return TOOLS
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+    """Route tool calls to the appropriate handler."""
+    handlers = {
+        "decompose": handle_decompose,
+        "research": handle_research,
+        "validate": handle_validate,
+        "solve": handle_solve,
+        "solve_scene": handle_solve_scene,
+        "verify": handle_verify,
+    }
+
+    handler = handlers.get(name)
+    if handler is None:
+        return [
+            TextContent(
+                type="text", text=json.dumps({"error": f"Unknown tool: {name}"})
+            )
+        ]
+
+    try:
+        result = handler(arguments)
+        return [TextContent(type="text", text=json.dumps(result, default=str))]
+    except Exception as exc:
+        return [
+            TextContent(
+                type="text",
+                text=json.dumps({"error": str(exc), "tool": name}),
+            )
+        ]
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+async def _run() -> None:
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream, write_stream, server.create_initialization_options()
+        )
+
+
+def main() -> None:
+    import asyncio
+
+    asyncio.run(_run())
+
+
+if __name__ == "__main__":
+    main()

cortex/tools/__init__.py

@@ -0,0 +1 @@
+"""MCP tool handlers for Cortex."""

cortex/tools/decompose.py

@@ -0,0 +1,24 @@
+"""Tool handler for the ``decompose`` MCP tool."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cortex.core.decomposer import decompose
+from cortex.types import _to_dict
+
+
+def handle_decompose(arguments: dict[str, Any]) -> dict[str, Any]:
+    """Parse input and delegate to the decomposer."""
+    subject: str = arguments["subject"]
+    variant: str = arguments.get("variant", "")
+    scope: str = arguments.get("scope", "object")
+    detail_level: str = arguments.get("detail_level", "detailed")
+
+    result = decompose(
+        subject=subject,
+        variant=variant,
+        scope=scope,
+        detail_level=detail_level,
+    )
+    return _to_dict(result)

cortex/tools/research.py

@@ -0,0 +1,17 @@
+"""Tool handler for the ``research`` MCP tool."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cortex.core.decomposer import research
+from cortex.types import _to_dict
+
+
+def handle_research(arguments: dict[str, Any]) -> dict[str, Any]:
+    """Parse input and delegate to the research checker."""
+    hierarchy: dict = arguments["hierarchy"]
+    filled_data: dict | None = arguments.get("filled_data")
+
+    result = research(hierarchy=hierarchy, filled_data=filled_data)
+    return _to_dict(result)

cortex/tools/solve.py

@@ -0,0 +1,16 @@
+"""Tool handler for the ``solve`` MCP tool."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cortex.core.solver import solve
+from cortex.tools.validate import _parse_recipe
+from cortex.types import _to_dict
+
+
+def handle_solve(arguments: dict[str, Any]) -> dict[str, Any]:
+    """Parse input and delegate to the solver."""
+    recipe = _parse_recipe(arguments["recipe"])
+    result = solve(recipe)
+    return _to_dict(result)

cortex/tools/solve_scene.py

@@ -0,0 +1,57 @@
+"""Tool handler for the ``solve_scene`` MCP tool."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cortex.core.scene_solver import solve_scene
+from cortex.types import (
+    Dimensions,
+    PartSpec,
+    SceneConstraint,
+    SceneRecipe,
+    _to_dict,
+)
+
+
+def _parse_scene_recipe(raw: dict[str, Any]) -> SceneRecipe:
+    """Convert a raw JSON dict into a typed SceneRecipe."""
+    objects: dict[str, PartSpec] = {}
+    for name, spec in raw.get("objects", {}).items():
+        dims = spec.get("dimensions", {})
+        objects[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[SceneConstraint] = []
+    for c in raw.get("constraints", []):
+        constraints.append(
+            SceneConstraint(
+                type=c["type"],
+                object=c.get("object", c.get("objects", "")),
+                params=c.get("params", {}),
+            )
+        )
+
+    return SceneRecipe(
+        name=raw.get("name", ""),
+        bounds=raw.get("bounds", {"min": [0, 0, 0], "max": [10, 10, 10]}),
+        objects=objects,
+        zones=raw.get("zones", {}),
+        constraints=constraints,
+    )
+
+
+def handle_solve_scene(arguments: dict[str, Any]) -> dict[str, Any]:
+    """Parse input and delegate to the scene solver."""
+    recipe = _parse_scene_recipe(arguments["scene_recipe"])
+    result = solve_scene(recipe)
+    return _to_dict(result)