solidworks-mcp-python 1.5.0__py3-none-any.whl

solidworks_mcp/agents/retrieval_index.py

@@ -0,0 +1,164 @@
+"""Local retrieval index builder for feature-tree audits, tool docs, and failures."""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from .history_db import DEFAULT_DB_PATH, find_recent_errors
+
+
+def _chunk_text(text: str, chunk_size: int = 1000, overlap: int = 150) -> list[str]:
+    """Split long text into overlapping chunks for simple local retrieval.
+
+    Args:
+        text (str): Input text processed by the operation.
+        chunk_size (int): Maximum number of characters to keep in each chunk. Defaults to
+                          1000.
+        overlap (int): Number of overlapping characters between chunks. Defaults to 150.
+
+    Returns:
+        list[str]: A list containing the resulting items.
+    """
+    normalized = (text or "").strip()
+    if not normalized:
+        return []
+
+    if len(normalized) <= chunk_size:
+        return [normalized]
+
+    chunks: list[str] = []
+    start = 0
+    while start < len(normalized):
+        end = min(start + chunk_size, len(normalized))
+        chunks.append(normalized[start:end])
+        if end == len(normalized):
+            break
+        start = max(0, end - overlap)
+    return chunks
+
+
+def _read_text(path: Path) -> str:
+    """Build internal text.
+
+    Args:
+        path (Path): Filesystem path for the operation.
+
+    Returns:
+        str: The resulting text value.
+    """
+
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError:
+        return ""
+
+
+def build_local_retrieval_index(
+    *,
+    output_path: Path | None = None,
+    worked_examples_path: Path | None = None,
+    tool_catalog_dir: Path | None = None,
+    db_path: Path | None = None,
+    max_recent_errors: int = 200,
+) -> dict[str, Any]:
+    """Build a JSON retrieval index from local audits, tool docs, and failures.
+
+    Args:
+        output_path (Path | None): The output path value. Defaults to None.
+        worked_examples_path (Path | None): The worked examples path value. Defaults to
+                                            None.
+        tool_catalog_dir (Path | None): The tool catalog dir value. Defaults to None.
+        db_path (Path | None): The db path value. Defaults to None.
+        max_recent_errors (int): The max recent errors value. Defaults to 200.
+
+    Returns:
+        dict[str, Any]: A dictionary containing the resulting values.
+    """
+    if output_path is None:
+        output_path = Path(".solidworks_mcp") / "retrieval" / "local_index.json"
+    if worked_examples_path is None:
+        worked_examples_path = Path("docs") / "user-guide" / "worked-examples.md"
+    if tool_catalog_dir is None:
+        tool_catalog_dir = Path("docs") / "user-guide" / "tool-catalog"
+    if db_path is None:
+        db_path = DEFAULT_DB_PATH
+
+    chunks: list[dict[str, Any]] = []
+    chunk_id = 0
+
+    worked_text = _read_text(worked_examples_path)
+    for idx, chunk in enumerate(_chunk_text(worked_text), start=1):
+        chunk_id += 1
+        chunks.append(
+            {
+                "id": f"audit-worked-examples-{idx}",
+                "chunk_id": chunk_id,
+                "source_type": "feature_tree_audit",
+                "source": str(worked_examples_path),
+                "text": chunk,
+                "tags": ["audit", "worked_examples", "inspect_classify_delegate"],
+            }
+        )
+
+    if tool_catalog_dir.exists():
+        for doc_path in sorted(tool_catalog_dir.glob("*.md")):
+            if doc_path.name.lower() == "index.md":
+                continue
+            doc_text = _read_text(doc_path)
+            for idx, chunk in enumerate(_chunk_text(doc_text), start=1):
+                chunk_id += 1
+                chunks.append(
+                    {
+                        "id": f"tool-doc-{doc_path.stem}-{idx}",
+                        "chunk_id": chunk_id,
+                        "source_type": "tool_doc",
+                        "source": str(doc_path),
+                        "text": chunk,
+                        "tags": ["tool_catalog", doc_path.stem],
+                    }
+                )
+
+    for idx, error in enumerate(
+        find_recent_errors(limit=max_recent_errors, db_path=db_path),
+        start=1,
+    ):
+        chunk_id += 1
+        error_text = (
+            f"source={error.get('source')} | tool={error.get('tool_name')} | "
+            f"type={error.get('error_type')} | message={error.get('error_message')} | "
+            f"root_cause={error.get('root_cause')} | remediation={error.get('remediation')}"
+        )
+        chunks.append(
+            {
+                "id": f"failure-memory-{idx}",
+                "chunk_id": chunk_id,
+                "source_type": "failure_memory",
+                "source": str(db_path),
+                "text": error_text,
+                "tags": ["failure_memory", error.get("tool_name", "unknown")],
+                "created_at": error.get("created_at"),
+            }
+        )
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    payload: dict[str, Any] = {
+        "version": "1.0",
+        "generated_at": datetime.now(UTC).isoformat(),
+        "stats": {
+            "chunk_count": len(chunks),
+            "worked_examples_source": str(worked_examples_path),
+            "tool_catalog_source": str(tool_catalog_dir),
+            "failure_memory_source": str(db_path),
+        },
+        "chunks": chunks,
+    }
+
+    output_path.write_text(
+        json.dumps(payload, indent=2, ensure_ascii=True),
+        encoding="utf-8",
+    )
+    return payload

solidworks_mcp/agents/schemas.py

@@ -0,0 +1,165 @@
+"""Typed output schemas for agent prompt validation."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class Assumption(BaseModel):
+    """A single explicit assumption in an agent response.
+
+    Attributes:
+        statement (str): The statement value.
+    """
+
+    statement: str = Field(min_length=3)
+
+
+class Recommendation(BaseModel):
+    """A prioritized recommendation with rationale and risk.
+
+    Attributes:
+        rationale (str): The rationale value.
+        risk (Literal["low", "medium", "high"]): The risk value.
+        title (str): The title value.
+    """
+
+    title: str = Field(min_length=3)
+    rationale: str = Field(min_length=5)
+    risk: Literal["low", "medium", "high"]
+
+
+class ManufacturabilityReview(BaseModel):
+    """Validation shape for printability-focused agent responses.
+
+    Attributes:
+        assumptions (list[Assumption]): The assumptions value.
+        build_volume_check (str): The build volume check value.
+        orientation_guidance (str): The orientation guidance value.
+        recommendations (list[Recommendation]): The recommendations value.
+        summary (str): The summary value.
+        tolerance_clearance_notes (list[str]): The tolerance clearance notes value.
+    """
+
+    summary: str = Field(min_length=10)
+    assumptions: list[Assumption] = Field(default_factory=list)
+    recommendations: list[Recommendation] = Field(default_factory=list)
+    orientation_guidance: str = Field(min_length=5)
+    tolerance_clearance_notes: list[str] = Field(default_factory=list)
+    build_volume_check: str = Field(
+        description="Expected to state pass/fail and mitigation options when needed.",
+        min_length=5,
+    )
+
+
+class ToolRoutingDecision(BaseModel):
+    """Validation shape for tool-selection/skills documentation prompts.
+
+    Attributes:
+        fallback_strategy (list[str]): The fallback strategy value.
+        intent (str): The intent value.
+        selected_tool_group (str): The selected tool group value.
+        why (str): The why value.
+    """
+
+    intent: str = Field(min_length=3)
+    selected_tool_group: str = Field(min_length=3)
+    why: str = Field(min_length=10)
+    fallback_strategy: list[str] = Field(default_factory=list)
+
+
+class DocsPlan(BaseModel):
+    """Validation shape for docs-engineering responses.
+
+    Attributes:
+        audience (str): The audience value.
+        decisions (list[ToolRoutingDecision]): The decisions value.
+        demo_steps (list[str]): The demo steps value.
+        objective (str): The objective value.
+        sections (list[str]): The sections value.
+    """
+
+    audience: str = Field(min_length=3)
+    objective: str = Field(min_length=5)
+    sections: list[str] = Field(default_factory=list)
+    decisions: list[ToolRoutingDecision] = Field(default_factory=list)
+    demo_steps: list[str] = Field(default_factory=list)
+
+
+class FeatureStep(BaseModel):
+    """One step in a part reconstruction plan.
+
+    Attributes:
+        description (str): The description value.
+        mcp_call (str): The mcp call value.
+        step_number (int): The step number value.
+        tool_name (str): The tool name value.
+    """
+
+    step_number: int = Field(ge=1)
+    tool_name: str = Field(
+        min_length=2, description="MCP tool or action, e.g. create_extrusion"
+    )
+    description: str = Field(min_length=5)
+    mcp_call: str = Field(
+        min_length=5,
+        description="Python-style call string, e.g. create_extrusion(sketch_name='Sketch1', depth=10.0)",
+    )
+
+
+class ReconstructionPlan(BaseModel):
+    """Structured plan for recreating a SolidWorks part from scratch using MCP tools.
+
+    Attributes:
+        analysis_summary (str): The analysis summary value.
+        assembly_mates (list[str]): The assembly mates value.
+        complexity_tier (Literal[1, 2, 3, 4]): The complexity tier value.
+        feature_sequence (list[FeatureStep]): The feature sequence value.
+        part_name (str): The part name value.
+        validation_strategy (str): The validation strategy value.
+        vba_required (bool): The vba required value.
+    """
+
+    part_name: str = Field(min_length=2)
+    complexity_tier: Literal[1, 2, 3, 4] = Field(
+        description="1=Simple revolve/extrude, 2=Multi-sketch, 3=VBA/loft, 4=Assembly"
+    )
+    analysis_summary: str = Field(
+        min_length=10,
+        description="Brief summary of the part's key geometry and design intent.",
+    )
+    feature_sequence: list[FeatureStep] = Field(
+        min_length=1, description="Ordered list of MCP tool calls to recreate the part."
+    )
+    vba_required: bool = Field(
+        description="True if any feature requires generate_vba_part_modeling + execute_macro."
+    )
+    assembly_mates: list[str] = Field(
+        default_factory=list,
+        description="Mate descriptions for assembly parts, e.g. 'coincident: shaft_axis to yoke_bore'.",
+    )
+    validation_strategy: str = Field(
+        min_length=5,
+        description="How to confirm the reconstruction matches the original (e.g. pixel diff, mass properties).",
+    )
+
+
+class RecoverableFailure(BaseModel):
+    """Typed failure output used when agent needs user-guided retry.
+
+    Attributes:
+        explanation (str): The explanation value.
+        remediation_steps (list[str]): The remediation steps value.
+        retry_focus (str | None): The retry focus value.
+        should_retry (bool): The should retry value.
+    """
+
+    explanation: str = Field(min_length=8)
+    remediation_steps: list[str] = Field(default_factory=list)
+    retry_focus: str | None = Field(
+        default=None,
+        description="Optional hint on what to change in the next prompt.",
+    )
+    should_retry: bool = True

solidworks_mcp/agents/smoke_test.py

@@ -0,0 +1,285 @@
+"""CLI for running validated prompt smoke tests against custom agent files."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from enum import StrEnum
+from typing import Annotated
+
+import typer
+
+from .harness import pretty_json, run_validated_prompt
+from .schemas import (
+    DocsPlan,
+    ManufacturabilityReview,
+    ReconstructionPlan,
+    RecoverableFailure,
+)
+
+app = typer.Typer(
+    name="smoke-test",
+    help="Run validated custom-agent prompt tests against the SolidWorks MCP agents.",
+    no_args_is_help=True,
+)
+
+
+class SchemaChoice(StrEnum):
+    """Handle schema choice.
+
+    Attributes:
+        docs (Any): The docs value.
+        manufacturability (Any): The manufacturability value.
+        reconstruction (Any): The reconstruction value.
+    """
+
+    manufacturability = "manufacturability"
+    docs = "docs"
+    reconstruction = "reconstruction"
+
+
+def _resolve_model(
+    anthropic: bool,
+    claude_model: str,
+    github_models: bool,
+    github_model: str,
+    model: str | None,
+) -> str:
+    """Resolve effective model id from CLI options.
+
+    Args:
+        anthropic (bool): The anthropic value.
+        claude_model (str): The claude model value.
+        github_models (bool): The github models value.
+        github_model (str): The github model value.
+        model (str | None): The model value.
+
+    Returns:
+        str: The resulting text value.
+
+    Raises:
+        BadParameter: --model is required unless --github-models or --anthropic is enabled.
+                      Recommended: --github-models (requires GH_TOKEN with models:read
+                      scope).
+    """
+    if github_models:
+        return f"github:{github_model}"
+
+    if anthropic:
+        return f"anthropic:{claude_model}"
+
+    if not model:
+        raise typer.BadParameter(
+            "--model is required unless --github-models or --anthropic is enabled. "
+            "Recommended: --github-models (requires GH_TOKEN with models:read scope).",
+            param_hint="'--model'",
+        )
+
+    return model
+
+
+def _ensure_provider_credentials(model: str) -> None:
+    """Provide actionable credential guidance before model invocation.
+
+    Args:
+        model (str): The model value.
+
+    Returns:
+        None: None.
+
+    Raises:
+        BadParameter: OPENAI_API_KEY is not set. Copilot subscription cannot be reused as an
+                      OpenAI API key for local pydantic-ai scripts. Use --github-models
+                      instead.
+    """
+    if model.startswith("github:"):
+        github_token = os.getenv("GITHUB_API_KEY") or os.getenv("GH_TOKEN")
+        if not github_token:
+            # Fall back to `gh auth token` if the gh CLI is available and authenticated.
+            try:
+                import subprocess
+
+                result = subprocess.run(
+                    ["gh", "auth", "token"], capture_output=True, text=True, timeout=5
+                )
+                if result.returncode == 0:
+                    github_token = result.stdout.strip()
+            except Exception:
+                pass
+        if not github_token:
+            raise typer.BadParameter(
+                "GitHub Models requires GITHUB_API_KEY (or GH_TOKEN) with models:read scope.\n"
+                "Options:\n"
+                "  1. Run: gh auth login  (GitHub CLI — free with Copilot subscription)\n"
+                "  2. Or set: $env:GH_TOKEN = 'github_pat_...'",
+                param_hint="'--github-models'",
+            )
+        # pydantic-ai GitHubProvider looks for GITHUB_API_KEY.
+        os.environ.setdefault("GITHUB_API_KEY", github_token)
+        return
+
+    if model.startswith("anthropic:") and not os.getenv("ANTHROPIC_API_KEY"):
+        raise typer.BadParameter(
+            "ANTHROPIC_API_KEY is not set.\n"
+            "Export your key before running smoke_test:\n"
+            "  $env:ANTHROPIC_API_KEY = 'sk-ant-...'\n"
+            "Or use --github-models to run via GitHub Models with a GitHub PAT.",
+            param_hint="'--anthropic'",
+        )
+
+    if model.startswith("openai:") and not os.getenv("OPENAI_API_KEY"):
+        raise typer.BadParameter(
+            "OPENAI_API_KEY is not set. Copilot subscription cannot be reused as an "
+            "OpenAI API key for local pydantic-ai scripts. "
+            "Use --github-models instead.",
+            param_hint="'--model'",
+        )
+
+
+async def _run(
+    agent_file: str,
+    model_name: str,
+    prompt: str,
+    schema: SchemaChoice,
+    max_retries_on_recoverable: int,
+) -> int:
+    """Build internal run.
+
+    Args:
+        agent_file (str): The agent file value.
+        model_name (str): Embedding model name to use.
+        prompt (str): The prompt value.
+        schema (SchemaChoice): The schema value.
+        max_retries_on_recoverable (int): The max retries on recoverable value.
+
+    Returns:
+        int: The computed numeric result.
+    """
+
+    schema_type: (
+        type[ManufacturabilityReview] | type[ReconstructionPlan] | type[DocsPlan]
+    )
+
+    if schema == SchemaChoice.manufacturability:
+        schema_type = ManufacturabilityReview
+    elif schema == SchemaChoice.reconstruction:
+        schema_type = ReconstructionPlan
+    else:
+        schema_type = DocsPlan
+    result = await run_validated_prompt(
+        agent_file_name=agent_file,
+        model_name=model_name,
+        user_prompt=prompt,
+        result_type=schema_type,
+        max_retries_on_recoverable=max_retries_on_recoverable,
+    )
+
+    if isinstance(result, RecoverableFailure):
+        typer.echo("RecoverableFailure returned after retry attempts:")
+    typer.echo(pretty_json(result))
+    return 0
+
+
+@app.command()
+def run(
+    agent_file: Annotated[
+        str,
+        typer.Option(
+            "--agent-file", help="Agent filename in .github/agents/", show_default=False
+        ),
+    ],
+    prompt: Annotated[
+        str,
+        typer.Option("--prompt", help="User prompt to run", show_default=False),
+    ],
+    github_models: Annotated[
+        bool,
+        typer.Option(
+            "--github-models",
+            help="Use GitHub Models provider (recommended). Requires GH_TOKEN or GITHUB_API_KEY with models:read scope.",
+        ),
+    ] = False,
+    github_model: Annotated[
+        str,
+        typer.Option(
+            "--github-model",
+            help="GitHub Models catalog id, e.g. openai/gpt-4.1 or mistral-ai/mistral-large.",
+        ),
+    ] = "openai/gpt-4.1",
+    anthropic: Annotated[
+        bool,
+        typer.Option(
+            "--anthropic",
+            help="Use Anthropic Claude (requires ANTHROPIC_API_KEY with active billing).",
+        ),
+    ] = False,
+    claude_model: Annotated[
+        str,
+        typer.Option(
+            "--claude-model",
+            help="Anthropic model id, e.g. claude-sonnet-4-6 or claude-opus-4-6.",
+        ),
+    ] = "claude-sonnet-4-6",
+    model: Annotated[
+        str | None,
+        typer.Option(
+            "--model",
+            help="Explicit PydanticAI model spec, e.g. openai:gpt-4.1. Overridden by --anthropic/--github-models.",
+        ),
+    ] = None,
+    schema: Annotated[
+        SchemaChoice,
+        typer.Option(
+            "--schema", help="Validation schema expected from the model output."
+        ),
+    ] = SchemaChoice.manufacturability,
+    max_retries_on_recoverable: Annotated[
+        int,
+        typer.Option(
+            "--max-retries-on-recoverable",
+            help="Automatic retry attempts when model returns RecoverableFailure.",
+        ),
+    ] = 1,
+) -> None:
+    """Run a validated custom-agent prompt test and print structured JSON output.
+
+    Args:
+        agent_file: Agent filename under `.github/agents/`.
+        prompt: User prompt to execute against the agent.
+        github_models: Use GitHub Models provider.
+        github_model: GitHub model id when `github_models` is enabled.
+        anthropic: Use Anthropic provider.
+        claude_model: Anthropic model id when `anthropic` is enabled.
+        model: Explicit provider-qualified model (for example `openai:gpt-4.1`).
+        schema: Expected structured output schema.
+        max_retries_on_recoverable: Retries for `RecoverableFailure` outputs.
+
+    Returns:
+        None: None.
+
+    Raises:
+        SystemExit: Always raised with the command exit code.
+    """
+    model_name = _resolve_model(
+        anthropic, claude_model, github_models, github_model, model
+    )
+    _ensure_provider_credentials(model_name)
+    raise SystemExit(
+        asyncio.run(
+            _run(agent_file, model_name, prompt, schema, max_retries_on_recoverable)
+        )
+    )
+
+
+def main() -> None:
+    """Handle main.
+
+    Returns:
+        None: None.
+    """
+
+    app()
+
+
+if __name__ == "__main__":
+    main()