solidworks_mcp.agents.history_db

solidworks_mcp.agents.history_db

SQLModel persistence for agent runs and tool-error cataloging.

Attributes

DEFAULT_DB_PATH module-attribute

DEFAULT_DB_PATH = Path('.solidworks_mcp') / 'agent_memory.sqlite3'

Classes

AgentRun

Bases: SQLModel

One recorded agent run.

Attributes:

Name	Type	Description
agent_name	str	The agent name value.
created_at	str	The created at value.
id	int | None	The id value.
model_name	str | None	The model name value.
output_json	str | None	The output json value.
prompt	str	The prompt value.
run_id	str	The run id value.
status	str	The status value.

ConversationEvent

Bases: SQLModel

One message or system event in a conversation, linked to a run context.

Attributes:

Name	Type	Description
content_snippet	str	The content snippet value.
conversation_id	str	The conversation id value.
created_at	str	The created at value.
event_type	str	The event type value.
id	int | None	The id value.
metadata_json	str | None	The metadata json value.
role	str | None	The role value.
run_id	str | None	The run id value.

DesignSession

Bases: SQLModel

Persistent interactive design session metadata.

Attributes:

Name	Type	Description
accepted_family	str | None	The accepted family value.
created_at	str	The created at value.
current_checkpoint_index	int	The current checkpoint index value.
id	int | None	The id value.
metadata_json	str | None	The metadata json value.
session_id	str	The session id value.
source_mode	str	The source mode value.
status	str	The status value.
updated_at	str	The updated at value.
user_goal	str	The user goal value.

ErrorCatalog

Bases: SQLModel

Persisted error records for recovery recommendations.

Attributes:

Name	Type	Description
created_at	str	The created at value.
error_message	str	The error message value.
error_type	str	The error type value.
id	int | None	The id value.
remediation	str	The remediation value.
root_cause	str	The root cause value.
run_id	str | None	The run id value.
source	str	The source value.
tool_name	str	The tool name value.

ErrorRecord

Bases: BaseModel

A normalized error record from an MCP call or planning step.

Attributes:

Name	Type	Description
error_message	str	The error message value.
error_type	str	The error type value.
remediation	str	The remediation value.
root_cause	str	The root cause value.
source	str	The source value.
tool_name	str	The tool name value.

EvidenceLink

Bases: SQLModel

Evidence references used to justify planning decisions.

Attributes:

Name	Type	Description
checkpoint_id	int | None	The checkpoint id value.
created_at	str	The created at value.
id	int | None	The id value.
payload_json	str | None	The payload json value.
rationale	str | None	The rationale value.
relevance_score	float | None	The relevance score value.
session_id	str	The session id value.
source_id	str	The source id value.
source_type	str	The source type value.

ModelStateSnapshot

Bases: SQLModel

Rollback/diff snapshot of model state at a checkpoint.

Attributes:

Name	Type	Description
checkpoint_id	int | None	The checkpoint id value.
created_at	str	The created at value.
feature_tree_json	str | None	The feature tree json value.
id	int | None	The id value.
mass_properties_json	str | None	The mass properties json value.
model_path	str | None	The model path value.
screenshot_path	str | None	The screenshot path value.
session_id	str	The session id value.
state_fingerprint	str | None	The state fingerprint value.

PlanCheckpoint

Bases: SQLModel

One approval boundary in an interactive design session.

Attributes:

Name	Type	Description
approved_by_user	bool	The approved by user value.
checkpoint_index	int	The checkpoint index value.
created_at	str	The created at value.
executed	bool	The executed value.
id	int | None	The id value.
planned_action_json	str	The planned action json value.
result_json	str | None	The result json value.
rollback_snapshot_id	int | None	The rollback snapshot id value.
session_id	str	The session id value.
title	str	The title value.
updated_at	str	The updated at value.

SketchGraphSnapshot

Bases: SQLModel

Lightweight relational sketch graph storage (Section F).

Attributes:

Name	Type	Description
created_at	str	The created at value.
edges_json	str	The edges json value.
graph_format	str	The graph format value.
id	int | None	The id value.
metadata_json	str | None	The metadata json value.
model_path	str | None	The model path value.
nodes_json	str	The nodes json value.
session_id	str	The session id value.

SoCCheckpoint

Bases: SQLModel

Named save point in a SolidWorks-as-Code session.

A checkpoint ties together a human label, the saved .sldprt file that represents the model state at that point, and the range of ToolCallRecord rows that produced it. The exporter uses this to emit structured comment blocks; soc_rewind uses the file_path to restore the model; soc_pickup uses snapshot_id to diff against the current feature tree.

Attributes:

Name	Type	Description
file_path	str	Path to the .sldprt saved at this checkpoint.
first_record_id	int | None	First ToolCallRecord.id in this block.
id	int | None	Primary key.
label	str	Short human name for this checkpoint.
last_record_id	int | None	Last ToolCallRecord.id in this block.
session_id	str	Owning SoC session.
snapshot_id	int | None	FK to ModelStateSnapshot (feature tree, mass props).
created_at	str	ISO timestamp.

ToolCallRecord

Bases: SQLModel

Execution log for tool calls scoped to session/checkpoint.

Attributes:

Name	Type	Description
checkpoint_id	int | None	The checkpoint id value.
created_at	str	The created at value.
id	int | None	The id value.
input_json	str | None	The input json value.
latency_ms	float | None	The latency ms value.
output_json	str | None	The output json value.
run_id	str | None	The run id value.
session_id	str	The session id value.
status	str | None	Lifecycle status — None (active), 'reverted'.
success	bool	The success value.
tool_name	str	The tool name value.

ToolEvent

Bases: SQLModel

One tool lifecycle event linked to a run.

Attributes:

Name	Type	Description
created_at	str	The created at value.
id	int | None	The id value.
payload_json	str | None	The payload json value.
phase	str	The phase value.
run_id	str	The run id value.
tool_name	str	The tool name value.

Functions:

_build_engine

_build_engine(db_path: Path | None = None) -> Any

Build a local SQLite engine from the configured path.

Parameters:

Name	Type	Description	Default
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Name	Type	Description
Any	Any	SQLAlchemy engine instance for the resolved SQLite path.

Source code in src/solidworks_mcp/agents/history_db.py

def _build_engine(db_path: Path | None = None) -> Any:
    """Build a local SQLite engine from the configured path.

    Args:
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        Any: SQLAlchemy engine instance for the resolved SQLite path.
    """
    resolved = db_path or DEFAULT_DB_PATH
    resolved.parent.mkdir(parents=True, exist_ok=True)
    # NullPool closes sqlite connections immediately after each session/transaction,
    # which prevents a long-lived pool from surfacing ResourceWarning noise at process exit.
    return create_engine(f"sqlite:///{resolved}", echo=False, poolclass=NullPool)

_utc_now_iso

_utc_now_iso() -> str

Build internal utc now iso.

Returns:

Name	Type	Description
str	str	The resulting text value.

Source code in src/solidworks_mcp/agents/history_db.py

def _utc_now_iso() -> str:
    """Build internal utc now iso.

    Returns:
        str: The resulting text value.
    """

    return datetime.now(UTC).isoformat()

create_soc_checkpoint

create_soc_checkpoint(*, session_id: str, label: str, file_path: str, first_record_id: int | None = None, last_record_id: int | None = None, snapshot_id: int | None = None, db_path: Path | None = None) -> int

Insert a SoCCheckpoint and return its id.

Parameters:

Name	Type	Description	Default
session_id	str	Owning SoC session.	required
label	str	Short human name (e.g. "base-extrude").	required
file_path	str	Path to the .sldprt saved at this checkpoint.	required
first_record_id	int | None	First ToolCallRecord.id in this block.	None
last_record_id	int | None	Last ToolCallRecord.id in this block.	None
snapshot_id	int | None	FK to ModelStateSnapshot.	None
db_path	Path | None	Override default SQLite path.	None

Returns:

Name	Type	Description
int	int	The new SoCCheckpoint.id.

Source code in src/solidworks_mcp/agents/history_db.py

def create_soc_checkpoint(
    *,
    session_id: str,
    label: str,
    file_path: str,
    first_record_id: int | None = None,
    last_record_id: int | None = None,
    snapshot_id: int | None = None,
    db_path: Path | None = None,
) -> int:
    """Insert a SoCCheckpoint and return its id.

    Args:
        session_id (str): Owning SoC session.
        label (str): Short human name (e.g. "base-extrude").
        file_path (str): Path to the .sldprt saved at this checkpoint.
        first_record_id (int | None): First ToolCallRecord.id in this block.
        last_record_id (int | None): Last ToolCallRecord.id in this block.
        snapshot_id (int | None): FK to ModelStateSnapshot.
        db_path (Path | None): Override default SQLite path.

    Returns:
        int: The new SoCCheckpoint.id.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        row = SoCCheckpoint(
            session_id=session_id,
            label=label,
            file_path=file_path,
            first_record_id=first_record_id,
            last_record_id=last_record_id,
            snapshot_id=snapshot_id,
            created_at=_utc_now_iso(),
        )
        session.add(row)
        session.commit()
        session.refresh(row)
        return int(row.id)  # type: ignore[arg-type]

find_conversation_events

find_conversation_events(conversation_id: str, db_path: Path | None = None) -> list[dict[str, Any]]

Retrieve all events for a conversation, ordered by creation time.

Parameters:

Name	Type	Description	Default
conversation_id	str	The conversation id value.	required
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: A list containing the resulting items.

Source code in src/solidworks_mcp/agents/history_db.py

def find_conversation_events(
    conversation_id: str, db_path: Path | None = None
) -> list[dict[str, Any]]:
    """Retrieve all events for a conversation, ordered by creation time.

    Args:
        conversation_id (str): The conversation id value.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        list[dict[str, Any]]: A list containing the resulting items.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        rows = session.exec(
            select(ConversationEvent)
            .where(ConversationEvent.conversation_id == conversation_id)
            .order_by(ConversationEvent.id.asc())  # type: ignore[union-attr]
        ).all()

    return [
        {
            "id": row.id,
            "conversation_id": row.conversation_id,
            "run_id": row.run_id,
            "event_type": row.event_type,
            "role": row.role,
            "content_snippet": row.content_snippet,
            "metadata_json": row.metadata_json,
            "created_at": row.created_at,
        }
        for row in rows
    ]

find_recent_errors

find_recent_errors(limit: int = 20, db_path: Path | None = None) -> list[dict[str, Any]]

Return recent errors so agents can avoid repeated failing states.

Parameters:

Name	Type	Description	Default
limit	int	The limit value. Defaults to 20.	20
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: A list containing the resulting items.

Source code in src/solidworks_mcp/agents/history_db.py

def find_recent_errors(
    limit: int = 20, db_path: Path | None = None
) -> list[dict[str, Any]]:
    """Return recent errors so agents can avoid repeated failing states.

    Args:
        limit (int): The limit value. Defaults to 20.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        list[dict[str, Any]]: A list containing the resulting items.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        rows = session.exec(
            select(ErrorCatalog).order_by(ErrorCatalog.id.desc()).limit(limit)  # type: ignore[union-attr]
        ).all()

    return [
        {
            "run_id": row.run_id,
            "source": row.source,
            "tool_name": row.tool_name,
            "error_type": row.error_type,
            "error_message": row.error_message,
            "root_cause": row.root_cause,
            "remediation": row.remediation,
            "created_at": row.created_at,
        }
        for row in rows
    ]

find_run_timeline

find_run_timeline(run_id: str, db_path: Path | None = None) -> dict[str, Any]

Reconstruct a complete timeline for one run, joining runs, tool events, and conversation events.

Parameters:

Name	Type	Description	Default
run_id	str	The run id value.	required
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: A dictionary containing the resulting values.

Source code in src/solidworks_mcp/agents/history_db.py

def find_run_timeline(run_id: str, db_path: Path | None = None) -> dict[str, Any]:
    """Reconstruct a complete timeline for one run, joining runs, tool events, and conversation events.

    Args:
        run_id (str): The run id value.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        dict[str, Any]: A dictionary containing the resulting values.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)

    timeline: dict[str, Any] = {
        "run_id": run_id,
        "run_info": None,
        "events": [],
    }

    with Session(engine) as session:
        run_row = session.exec(
            select(AgentRun).where(AgentRun.run_id == run_id)
        ).first()

        if run_row:
            timeline["run_info"] = {
                "agent_name": run_row.agent_name,
                "prompt_preview": run_row.prompt[:200] if run_row.prompt else None,
                "model_name": run_row.model_name,
                "status": run_row.status,
                "created_at": run_row.created_at,
            }

        tool_events = session.exec(
            select(ToolEvent)
            .where(ToolEvent.run_id == run_id)
            .order_by(ToolEvent.id.asc())  # type: ignore[union-attr]
        ).all()

        convo_events = session.exec(
            select(ConversationEvent)
            .where(ConversationEvent.run_id == run_id)
            .order_by(ConversationEvent.id.asc())  # type: ignore[union-attr]
        ).all()

        events = []
        for evt in tool_events:
            events.append(
                {
                    "timestamp": evt.created_at,
                    "event_type": "tool",
                    "tool_name": evt.tool_name,
                    "phase": evt.phase,
                    "payload_preview": evt.payload_json[:100]
                    if evt.payload_json
                    else None,
                }
            )

        for conv_evt in convo_events:
            events.append(
                {
                    "timestamp": conv_evt.created_at,
                    "event_type": "message",
                    "role": conv_evt.role,
                    "content_preview": conv_evt.content_snippet[:100],
                    "metadata": conv_evt.metadata_json,
                }
            )

        events.sort(key=lambda e: e["timestamp"] or "")
        timeline["events"] = events

    return timeline

get_design_session

get_design_session(session_id: str, db_path: Path | None = None) -> dict[str, Any] | None

Return one session row as a dictionary.

Parameters:

Name	Type	Description	Default
session_id	str	The session id value.	required
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Type	Description
dict[str, Any] | None	dict[str, Any] | None: A dictionary containing the resulting values.

Source code in src/solidworks_mcp/agents/history_db.py

def get_design_session(
    session_id: str, db_path: Path | None = None
) -> dict[str, Any] | None:
    """Return one session row as a dictionary.

    Args:
        session_id (str): The session id value.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        dict[str, Any] | None: A dictionary containing the resulting values.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        row = session.exec(
            select(DesignSession).where(DesignSession.session_id == session_id)
        ).first()

    if row is None:
        return None
    return {
        "session_id": row.session_id,
        "user_goal": row.user_goal,
        "source_mode": row.source_mode,
        "accepted_family": row.accepted_family,
        "status": row.status,
        "current_checkpoint_index": row.current_checkpoint_index,
        "metadata_json": row.metadata_json,
        "created_at": row.created_at,
        "updated_at": row.updated_at,
    }

get_soc_checkpoint

get_soc_checkpoint(session_id: str, label: str, db_path: Path | None = None) -> dict[str, Any] | None

Fetch a single SoCCheckpoint by session + label.

Parameters:

Name	Type	Description	Default
session_id	str	Owning SoC session.	required
label	str	Checkpoint label to look up.	required
db_path	Path | None	Override default SQLite path.	None

Returns:

Type	Description
dict[str, Any] | None	dict[str, Any] | None: Checkpoint dict or None if not found.

Source code in src/solidworks_mcp/agents/history_db.py

def get_soc_checkpoint(
    session_id: str,
    label: str,
    db_path: Path | None = None,
) -> dict[str, Any] | None:
    """Fetch a single SoCCheckpoint by session + label.

    Args:
        session_id (str): Owning SoC session.
        label (str): Checkpoint label to look up.
        db_path (Path | None): Override default SQLite path.

    Returns:
        dict[str, Any] | None: Checkpoint dict or None if not found.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        row = session.exec(
            select(SoCCheckpoint)
            .where(SoCCheckpoint.session_id == session_id)
            .where(SoCCheckpoint.label == label)
            .order_by(SoCCheckpoint.id.desc())  # type: ignore[union-attr]
        ).first()
    if row is None:
        return None
    return {
        "id": row.id,
        "session_id": row.session_id,
        "label": row.label,
        "file_path": row.file_path,
        "first_record_id": row.first_record_id,
        "last_record_id": row.last_record_id,
        "snapshot_id": row.snapshot_id,
        "created_at": row.created_at,
    }

init_db

init_db(db_path: Path | None = None) -> Path

Create SQLModel tables used by the lightweight agent memory system.

Parameters:

Name	Type	Description	Default
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Name	Type	Description
Path	Path	The result produced by the operation.

Source code in src/solidworks_mcp/agents/history_db.py

def init_db(db_path: Path | None = None) -> Path:
    """Create SQLModel tables used by the lightweight agent memory system.

    Args:
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        Path: The result produced by the operation.
    """
    resolved = db_path or DEFAULT_DB_PATH
    engine = _build_engine(resolved)
    try:
        SQLModel.metadata.create_all(engine)
    finally:
        engine.dispose()
    return resolved

insert_conversation_event

insert_conversation_event(*, conversation_id: str, event_type: str, content_snippet: str, role: str | None = None, run_id: str | None = None, metadata_json: str | None = None, db_path: Path | None = None) -> None

Record a conversation event (message, system event, or tool call) linked to a run.

Parameters:

Name	Type	Description	Default
conversation_id	str	The conversation id value.	required
event_type	str	The event type value.	required
content_snippet	str	The content snippet value.	required
role	str | None	The role value. Defaults to None.	None
run_id	str | None	The run id value. Defaults to None.	None
metadata_json	str | None	The metadata json value. Defaults to None.	None
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Name	Type	Description
None	None	None.

Source code in src/solidworks_mcp/agents/history_db.py

def insert_conversation_event(
    *,
    conversation_id: str,
    event_type: str,
    content_snippet: str,
    role: str | None = None,
    run_id: str | None = None,
    metadata_json: str | None = None,
    db_path: Path | None = None,
) -> None:
    """Record a conversation event (message, system event, or tool call) linked to a run.

    Args:
        conversation_id (str): The conversation id value.
        event_type (str): The event type value.
        content_snippet (str): The content snippet value.
        role (str | None): The role value. Defaults to None.
        run_id (str | None): The run id value. Defaults to None.
        metadata_json (str | None): The metadata json value. Defaults to None.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        None: None.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        session.add(
            ConversationEvent(
                conversation_id=conversation_id,
                run_id=run_id,
                event_type=event_type,
                role=role,
                content_snippet=content_snippet,
                metadata_json=metadata_json,
                created_at=_utc_now_iso(),
            )
        )
        session.commit()

insert_error

insert_error(record: ErrorRecord, run_id: str | None = None, db_path: Path | None = None) -> None

Persist an error with normalized root cause and remediation guidance.

Parameters:

Name	Type	Description	Default
record	ErrorRecord	The record value.	required
run_id	str | None	The run id value. Defaults to None.	None
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Name	Type	Description
None	None	None.

Source code in src/solidworks_mcp/agents/history_db.py

def insert_error(
    record: ErrorRecord, run_id: str | None = None, db_path: Path | None = None
) -> None:
    """Persist an error with normalized root cause and remediation guidance.

    Args:
        record (ErrorRecord): The record value.
        run_id (str | None): The run id value. Defaults to None.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        None: None.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        session.add(
            ErrorCatalog(
                run_id=run_id,
                source=record.source,
                tool_name=record.tool_name,
                error_type=record.error_type,
                error_message=record.error_message,
                root_cause=record.root_cause,
                remediation=record.remediation,
                created_at=_utc_now_iso(),
            )
        )
        session.commit()

insert_evidence_link

insert_evidence_link(*, session_id: str, source_type: str, source_id: str, checkpoint_id: int | None = None, relevance_score: float | None = None, rationale: str | None = None, payload_json: str | None = None, db_path: Path | None = None) -> None

Insert one evidence row used by planning/classification.

Parameters:

Name	Type	Description	Default
session_id	str	The session id value.	required
source_type	str	The source type value.	required
source_id	str	The source id value.	required
checkpoint_id	int | None	The checkpoint id value. Defaults to None.	None
relevance_score	float | None	The relevance score value. Defaults to None.	None
rationale	str | None	The rationale value. Defaults to None.	None
payload_json	str | None	The payload json value. Defaults to None.	None
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Name	Type	Description
None	None	None.

Source code in src/solidworks_mcp/agents/history_db.py

def insert_evidence_link(
    *,
    session_id: str,
    source_type: str,
    source_id: str,
    checkpoint_id: int | None = None,
    relevance_score: float | None = None,
    rationale: str | None = None,
    payload_json: str | None = None,
    db_path: Path | None = None,
) -> None:
    """Insert one evidence row used by planning/classification.

    Args:
        session_id (str): The session id value.
        source_type (str): The source type value.
        source_id (str): The source id value.
        checkpoint_id (int | None): The checkpoint id value. Defaults to None.
        relevance_score (float | None): The relevance score value. Defaults to None.
        rationale (str | None): The rationale value. Defaults to None.
        payload_json (str | None): The payload json value. Defaults to None.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        None: None.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        session.add(
            EvidenceLink(
                session_id=session_id,
                checkpoint_id=checkpoint_id,
                source_type=source_type,
                source_id=source_id,
                relevance_score=relevance_score,
                rationale=rationale,
                payload_json=payload_json,
                created_at=_utc_now_iso(),
            )
        )
        session.commit()

insert_model_state_snapshot

insert_model_state_snapshot(*, session_id: str, checkpoint_id: int | None = None, model_path: str | None = None, feature_tree_json: str | None = None, mass_properties_json: str | None = None, screenshot_path: str | None = None, state_fingerprint: str | None = None, db_path: Path | None = None) -> int

Insert model snapshot row and return snapshot ID for rollback tracking.

Parameters:

Name	Type	Description	Default
session_id	str	The session id value.	required
checkpoint_id	int | None	The checkpoint id value. Defaults to None.	None
model_path	str | None	The model path value. Defaults to None.	None
feature_tree_json	str | None	The feature tree json value. Defaults to None.	None
mass_properties_json	str | None	The mass properties json value. Defaults to None.	None
screenshot_path	str | None	The screenshot path value. Defaults to None.	None
state_fingerprint	str | None	The state fingerprint value. Defaults to None.	None
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Name	Type	Description
int	int	The computed numeric result.

Source code in src/solidworks_mcp/agents/history_db.py

def insert_model_state_snapshot(
    *,
    session_id: str,
    checkpoint_id: int | None = None,
    model_path: str | None = None,
    feature_tree_json: str | None = None,
    mass_properties_json: str | None = None,
    screenshot_path: str | None = None,
    state_fingerprint: str | None = None,
    db_path: Path | None = None,
) -> int:
    """Insert model snapshot row and return snapshot ID for rollback tracking.

    Args:
        session_id (str): The session id value.
        checkpoint_id (int | None): The checkpoint id value. Defaults to None.
        model_path (str | None): The model path value. Defaults to None.
        feature_tree_json (str | None): The feature tree json value. Defaults to None.
        mass_properties_json (str | None): The mass properties json value. Defaults to None.
        screenshot_path (str | None): The screenshot path value. Defaults to None.
        state_fingerprint (str | None): The state fingerprint value. Defaults to None.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        int: The computed numeric result.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        row = ModelStateSnapshot(
            session_id=session_id,
            checkpoint_id=checkpoint_id,
            model_path=model_path,
            feature_tree_json=feature_tree_json,
            mass_properties_json=mass_properties_json,
            screenshot_path=screenshot_path,
            state_fingerprint=state_fingerprint,
            created_at=_utc_now_iso(),
        )
        session.add(row)
        session.commit()
        session.refresh(row)
        return int(row.id or 0)

insert_plan_checkpoint

insert_plan_checkpoint(*, session_id: str, checkpoint_index: int, title: str, planned_action_json: str, approved_by_user: bool = False, executed: bool = False, result_json: str | None = None, rollback_snapshot_id: int | None = None, db_path: Path | None = None) -> int

Insert a new checkpoint and return its ID.

Parameters:

Name	Type	Description	Default
session_id	str	The session id value.	required
checkpoint_index	int	The checkpoint index value.	required
title	str	The title value.	required
planned_action_json	str	The planned action json value.	required
approved_by_user	bool	The approved by user value. Defaults to False.	False
executed	bool	The executed value. Defaults to False.	False
result_json	str | None	The result json value. Defaults to None.	None
rollback_snapshot_id	int | None	The rollback snapshot id value. Defaults to None.	None
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Name	Type	Description
int	int	The computed numeric result.

Source code in src/solidworks_mcp/agents/history_db.py

def insert_plan_checkpoint(
    *,
    session_id: str,
    checkpoint_index: int,
    title: str,
    planned_action_json: str,
    approved_by_user: bool = False,
    executed: bool = False,
    result_json: str | None = None,
    rollback_snapshot_id: int | None = None,
    db_path: Path | None = None,
) -> int:
    """Insert a new checkpoint and return its ID.

    Args:
        session_id (str): The session id value.
        checkpoint_index (int): The checkpoint index value.
        title (str): The title value.
        planned_action_json (str): The planned action json value.
        approved_by_user (bool): The approved by user value. Defaults to False.
        executed (bool): The executed value. Defaults to False.
        result_json (str | None): The result json value. Defaults to None.
        rollback_snapshot_id (int | None): The rollback snapshot id value. Defaults to None.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        int: The computed numeric result.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    now = _utc_now_iso()
    with Session(engine) as session:
        row = PlanCheckpoint(
            session_id=session_id,
            checkpoint_index=checkpoint_index,
            title=title,
            planned_action_json=planned_action_json,
            approved_by_user=approved_by_user,
            executed=executed,
            result_json=result_json,
            rollback_snapshot_id=rollback_snapshot_id,
            created_at=now,
            updated_at=now,
        )
        session.add(row)
        session.commit()
        session.refresh(row)
        return int(row.id or 0)

insert_run

insert_run(*, run_id: str, agent_name: str, prompt: str, status: str, output_json: str | None, model_name: str | None, db_path: Path | None = None) -> None

Record one prompt run and optionally the validated output payload.

Parameters:

Name	Type	Description	Default
run_id	str	The run id value.	required
agent_name	str	The agent name value.	required
prompt	str	The prompt value.	required
status	str	The status value.	required
output_json	str | None	The output json value.	required
model_name	str | None	Embedding model name to use.	required
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Name	Type	Description
None	None	None.

Source code in src/solidworks_mcp/agents/history_db.py

def insert_run(
    *,
    run_id: str,
    agent_name: str,
    prompt: str,
    status: str,
    output_json: str | None,
    model_name: str | None,
    db_path: Path | None = None,
) -> None:
    """Record one prompt run and optionally the validated output payload.

    Args:
        run_id (str): The run id value.
        agent_name (str): The agent name value.
        prompt (str): The prompt value.
        status (str): The status value.
        output_json (str | None): The output json value.
        model_name (str | None): Embedding model name to use.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        None: None.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        session.add(
            AgentRun(
                run_id=run_id,
                agent_name=agent_name,
                prompt=prompt,
                model_name=model_name,
                status=status,
                output_json=output_json,
                created_at=_utc_now_iso(),
            )
        )
        session.commit()

insert_sketch_graph_snapshot

insert_sketch_graph_snapshot(*, session_id: str, nodes_json: str, edges_json: str, model_path: str | None = None, graph_format: str = 'json', metadata_json: str | None = None, db_path: Path | None = None) -> None

Store lightweight sketch graph snapshots in SQLite (Section F).

Parameters:

Name	Type	Description	Default
session_id	str	The session id value.	required
nodes_json	str	The nodes json value.	required
edges_json	str	The edges json value.	required
model_path	str | None	The model path value. Defaults to None.	None
graph_format	str	The graph format value. Defaults to "json".	'json'
metadata_json	str | None	The metadata json value. Defaults to None.	None
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Name	Type	Description
None	None	None.

Source code in src/solidworks_mcp/agents/history_db.py

def insert_sketch_graph_snapshot(
    *,
    session_id: str,
    nodes_json: str,
    edges_json: str,
    model_path: str | None = None,
    graph_format: str = "json",
    metadata_json: str | None = None,
    db_path: Path | None = None,
) -> None:
    """Store lightweight sketch graph snapshots in SQLite (Section F).

    Args:
        session_id (str): The session id value.
        nodes_json (str): The nodes json value.
        edges_json (str): The edges json value.
        model_path (str | None): The model path value. Defaults to None.
        graph_format (str): The graph format value. Defaults to "json".
        metadata_json (str | None): The metadata json value. Defaults to None.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        None: None.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        session.add(
            SketchGraphSnapshot(
                session_id=session_id,
                model_path=model_path,
                graph_format=graph_format,
                nodes_json=nodes_json,
                edges_json=edges_json,
                metadata_json=metadata_json,
                created_at=_utc_now_iso(),
            )
        )
        session.commit()

insert_tool_call_record

insert_tool_call_record(*, session_id: str, tool_name: str, checkpoint_id: int | None = None, run_id: str | None = None, input_json: str | None = None, output_json: str | None = None, success: bool = True, latency_ms: float | None = None, db_path: Path | None = None) -> None

Insert one tool call execution record.

Parameters:

Name	Type	Description	Default
session_id	str	The session id value.	required
tool_name	str	The tool name value.	required
checkpoint_id	int | None	The checkpoint id value. Defaults to None.	None
run_id	str | None	The run id value. Defaults to None.	None
input_json	str | None	The input json value. Defaults to None.	None
output_json	str | None	The output json value. Defaults to None.	None
success	bool	The success value. Defaults to True.	True
latency_ms	float | None	The latency ms value. Defaults to None.	None
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Name	Type	Description
None	None	None.

Source code in src/solidworks_mcp/agents/history_db.py

def insert_tool_call_record(
    *,
    session_id: str,
    tool_name: str,
    checkpoint_id: int | None = None,
    run_id: str | None = None,
    input_json: str | None = None,
    output_json: str | None = None,
    success: bool = True,
    latency_ms: float | None = None,
    db_path: Path | None = None,
) -> None:
    """Insert one tool call execution record.

    Args:
        session_id (str): The session id value.
        tool_name (str): The tool name value.
        checkpoint_id (int | None): The checkpoint id value. Defaults to None.
        run_id (str | None): The run id value. Defaults to None.
        input_json (str | None): The input json value. Defaults to None.
        output_json (str | None): The output json value. Defaults to None.
        success (bool): The success value. Defaults to True.
        latency_ms (float | None): The latency ms value. Defaults to None.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        None: None.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        session.add(
            ToolCallRecord(
                session_id=session_id,
                checkpoint_id=checkpoint_id,
                run_id=run_id,
                tool_name=tool_name,
                input_json=input_json,
                output_json=output_json,
                success=success,
                latency_ms=latency_ms,
                created_at=_utc_now_iso(),
            )
        )
        session.commit()

insert_tool_event

insert_tool_event(*, run_id: str, tool_name: str, phase: str, payload_json: str | None, db_path: Path | None = None) -> None

Store lifecycle events around MCP tool usage to aid troubleshooting.

Parameters:

Name	Type	Description	Default
run_id	str	The run id value.	required
tool_name	str	The tool name value.	required
phase	str	The phase value.	required
payload_json	str | None	The payload json value.	required
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Name	Type	Description
None	None	None.

Source code in src/solidworks_mcp/agents/history_db.py

def insert_tool_event(
    *,
    run_id: str,
    tool_name: str,
    phase: str,
    payload_json: str | None,
    db_path: Path | None = None,
) -> None:
    """Store lifecycle events around MCP tool usage to aid troubleshooting.

    Args:
        run_id (str): The run id value.
        tool_name (str): The tool name value.
        phase (str): The phase value.
        payload_json (str | None): The payload json value.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        None: None.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        session.add(
            ToolEvent(
                run_id=run_id,
                tool_name=tool_name,
                phase=phase,
                payload_json=payload_json,
                created_at=_utc_now_iso(),
            )
        )
        session.commit()

list_evidence_links

list_evidence_links(session_id: str, checkpoint_id: int | None = None, db_path: Path | None = None) -> list[dict[str, Any]]

List evidence rows for a session and optional checkpoint.

Parameters:

Name	Type	Description	Default
session_id	str	The session id value.	required
checkpoint_id	int | None	The checkpoint id value. Defaults to None.	None
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: A list containing the resulting items.

Source code in src/solidworks_mcp/agents/history_db.py

def list_evidence_links(
    session_id: str,
    checkpoint_id: int | None = None,
    db_path: Path | None = None,
) -> list[dict[str, Any]]:
    """List evidence rows for a session and optional checkpoint.

    Args:
        session_id (str): The session id value.
        checkpoint_id (int | None): The checkpoint id value. Defaults to None.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        list[dict[str, Any]]: A list containing the resulting items.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        query = select(EvidenceLink).where(EvidenceLink.session_id == session_id)
        if checkpoint_id is not None:
            query = query.where(EvidenceLink.checkpoint_id == checkpoint_id)
        rows = session.exec(query.order_by(EvidenceLink.id.asc())).all()  # type: ignore[union-attr]

    return [
        {
            "id": row.id,
            "session_id": row.session_id,
            "checkpoint_id": row.checkpoint_id,
            "source_type": row.source_type,
            "source_id": row.source_id,
            "relevance_score": row.relevance_score,
            "rationale": row.rationale,
            "payload_json": row.payload_json,
            "created_at": row.created_at,
        }
        for row in rows
    ]

list_model_state_snapshots

list_model_state_snapshots(session_id: str, db_path: Path | None = None) -> list[dict[str, Any]]

List snapshots for a session newest first for diff/rollback flows.

Parameters:

Name	Type	Description	Default
session_id	str	The session id value.	required
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: A list containing the resulting items.

Source code in src/solidworks_mcp/agents/history_db.py

def list_model_state_snapshots(
    session_id: str,
    db_path: Path | None = None,
) -> list[dict[str, Any]]:
    """List snapshots for a session newest first for diff/rollback flows.

    Args:
        session_id (str): The session id value.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        list[dict[str, Any]]: A list containing the resulting items.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        rows = session.exec(
            select(ModelStateSnapshot)
            .where(ModelStateSnapshot.session_id == session_id)
            .order_by(ModelStateSnapshot.id.desc())  # type: ignore[union-attr]
        ).all()

    return [
        {
            "id": row.id,
            "session_id": row.session_id,
            "checkpoint_id": row.checkpoint_id,
            "model_path": row.model_path,
            "feature_tree_json": row.feature_tree_json,
            "mass_properties_json": row.mass_properties_json,
            "screenshot_path": row.screenshot_path,
            "state_fingerprint": row.state_fingerprint,
            "created_at": row.created_at,
        }
        for row in rows
    ]

list_plan_checkpoints

list_plan_checkpoints(session_id: str, db_path: Path | None = None) -> list[dict[str, Any]]

List all checkpoints for a session.

Parameters:

Name	Type	Description	Default
session_id	str	The session id value.	required
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: A list containing the resulting items.

Source code in src/solidworks_mcp/agents/history_db.py

def list_plan_checkpoints(
    session_id: str,
    db_path: Path | None = None,
) -> list[dict[str, Any]]:
    """List all checkpoints for a session.

    Args:
        session_id (str): The session id value.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        list[dict[str, Any]]: A list containing the resulting items.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        rows = session.exec(
            select(PlanCheckpoint)
            .where(PlanCheckpoint.session_id == session_id)
            .order_by(PlanCheckpoint.checkpoint_index.asc())  # type: ignore[attr-defined]
        ).all()

    return [
        {
            "id": row.id,
            "session_id": row.session_id,
            "checkpoint_index": row.checkpoint_index,
            "title": row.title,
            "planned_action_json": row.planned_action_json,
            "approved_by_user": row.approved_by_user,
            "executed": row.executed,
            "result_json": row.result_json,
            "rollback_snapshot_id": row.rollback_snapshot_id,
            "created_at": row.created_at,
            "updated_at": row.updated_at,
        }
        for row in rows
    ]

list_sketch_graph_snapshots

list_sketch_graph_snapshots(session_id: str, model_path: str | None = None, db_path: Path | None = None) -> list[dict[str, Any]]

List sketch graph snapshots for a session.

Parameters:

Name	Type	Description	Default
session_id	str	The session id value.	required
model_path	str | None	The model path value. Defaults to None.	None
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: A list containing the resulting items.

Source code in src/solidworks_mcp/agents/history_db.py

def list_sketch_graph_snapshots(
    session_id: str,
    model_path: str | None = None,
    db_path: Path | None = None,
) -> list[dict[str, Any]]:
    """List sketch graph snapshots for a session.

    Args:
        session_id (str): The session id value.
        model_path (str | None): The model path value. Defaults to None.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        list[dict[str, Any]]: A list containing the resulting items.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        query = select(SketchGraphSnapshot).where(
            SketchGraphSnapshot.session_id == session_id
        )
        if model_path is not None:
            query = query.where(SketchGraphSnapshot.model_path == model_path)
        rows = session.exec(query.order_by(SketchGraphSnapshot.id.desc())).all()  # type: ignore[union-attr]

    return [
        {
            "id": row.id,
            "session_id": row.session_id,
            "model_path": row.model_path,
            "graph_format": row.graph_format,
            "nodes_json": row.nodes_json,
            "edges_json": row.edges_json,
            "metadata_json": row.metadata_json,
            "created_at": row.created_at,
        }
        for row in rows
    ]

list_soc_checkpoints

list_soc_checkpoints(session_id: str, db_path: Path | None = None) -> list[dict[str, Any]]

List SoCCheckpoints for a session in creation order.

Parameters:

Name	Type	Description	Default
session_id	str	Owning SoC session.	required
db_path	Path | None	Override default SQLite path.	None

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: Ordered list of checkpoint dicts.

Source code in src/solidworks_mcp/agents/history_db.py

def list_soc_checkpoints(
    session_id: str,
    db_path: Path | None = None,
) -> list[dict[str, Any]]:
    """List SoCCheckpoints for a session in creation order.

    Args:
        session_id (str): Owning SoC session.
        db_path (Path | None): Override default SQLite path.

    Returns:
        list[dict[str, Any]]: Ordered list of checkpoint dicts.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        rows = session.exec(
            select(SoCCheckpoint)
            .where(SoCCheckpoint.session_id == session_id)
            .order_by(SoCCheckpoint.id.asc())  # type: ignore[union-attr]
        ).all()
    return [
        {
            "id": row.id,
            "session_id": row.session_id,
            "label": row.label,
            "file_path": row.file_path,
            "first_record_id": row.first_record_id,
            "last_record_id": row.last_record_id,
            "snapshot_id": row.snapshot_id,
            "created_at": row.created_at,
        }
        for row in rows
    ]

list_tool_call_records

list_tool_call_records(session_id: str, checkpoint_id: int | None = None, db_path: Path | None = None, include_reverted: bool = False) -> list[dict[str, Any]]

List tool call records for a session and optional checkpoint.

Parameters:

Name	Type	Description	Default
session_id	str	The session id value.	required
checkpoint_id	int | None	The checkpoint id value. Defaults to None.	None
db_path	Path | None	The db path value. Defaults to None.	None
include_reverted	bool	Include records with status='reverted'. Defaults to False.	False

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: A list containing the resulting items.

Source code in src/solidworks_mcp/agents/history_db.py

def list_tool_call_records(
    session_id: str,
    checkpoint_id: int | None = None,
    db_path: Path | None = None,
    include_reverted: bool = False,
) -> list[dict[str, Any]]:
    """List tool call records for a session and optional checkpoint.

    Args:
        session_id (str): The session id value.
        checkpoint_id (int | None): The checkpoint id value. Defaults to None.
        db_path (Path | None): The db path value. Defaults to None.
        include_reverted (bool): Include records with status='reverted'. Defaults to False.

    Returns:
        list[dict[str, Any]]: A list containing the resulting items.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        query = select(ToolCallRecord).where(ToolCallRecord.session_id == session_id)
        if checkpoint_id is not None:
            query = query.where(ToolCallRecord.checkpoint_id == checkpoint_id)
        if not include_reverted:
            query = query.where(
                (ToolCallRecord.status == None) | (ToolCallRecord.status != "reverted")  # noqa: E711
            )
        rows = session.exec(query.order_by(ToolCallRecord.id.asc())).all()  # type: ignore[union-attr]

    return [
        {
            "id": row.id,
            "session_id": row.session_id,
            "checkpoint_id": row.checkpoint_id,
            "run_id": row.run_id,
            "tool_name": row.tool_name,
            "input_json": row.input_json,
            "output_json": row.output_json,
            "success": row.success,
            "latency_ms": row.latency_ms,
            "status": row.status,
            "created_at": row.created_at,
        }
        for row in rows
    ]

replace_plan_checkpoints

replace_plan_checkpoints(*, session_id: str, checkpoints: list[dict[str, Any]], db_path: Path | None = None) -> None

Replace all session checkpoints with a new ordered checkpoint list.

Parameters:

Name	Type	Description	Default
session_id	str	The session id value.	required
checkpoints	list[dict[str, Any]]	Replacement checkpoint records.	required
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Name	Type	Description
None	None	None.

Source code in src/solidworks_mcp/agents/history_db.py

def replace_plan_checkpoints(
    *,
    session_id: str,
    checkpoints: list[dict[str, Any]],
    db_path: Path | None = None,
) -> None:
    """Replace all session checkpoints with a new ordered checkpoint list.

    Args:
        session_id (str): The session id value.
        checkpoints (list[dict[str, Any]]): Replacement checkpoint records.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        None: None.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    now = _utc_now_iso()

    with Session(engine) as session:
        existing_rows = session.exec(
            select(PlanCheckpoint).where(PlanCheckpoint.session_id == session_id)
        ).all()
        for existing in existing_rows:
            session.delete(existing)

        for index, item in enumerate(checkpoints, start=1):
            planned_action_json = str(item.get("planned_action_json") or "{}")
            title = str(item.get("title") or f"Checkpoint {index}")
            approved_by_user = bool(item.get("approved_by_user", index == 1))
            row = PlanCheckpoint(
                session_id=session_id,
                checkpoint_index=int(item.get("checkpoint_index") or index),
                title=title,
                planned_action_json=planned_action_json,
                approved_by_user=approved_by_user,
                executed=False,
                result_json=None,
                rollback_snapshot_id=None,
                created_at=now,
                updated_at=now,
            )
            session.add(row)

        session.commit()

revert_tool_call_records

revert_tool_call_records(session_id: str, from_record_id: int, db_path: Path | None = None) -> int

Mark ToolCallRecords as reverted from from_record_id onward.

Sets status='reverted' on all records for the session with id >= from_record_id. Reverted records are excluded from list_tool_call_records() by default and from the soc_exporter output, so re-generating the script omits the rolled-back work.

Parameters:

Name	Type	Description	Default
session_id	str	The SoC session whose records should be reverted.	required
from_record_id	int	First record ID to mark as reverted (inclusive).	required
db_path	Path | None	Override default SQLite DB path.	None

Returns:

Name	Type	Description
int	int	Number of records marked reverted.

Source code in src/solidworks_mcp/agents/history_db.py

def revert_tool_call_records(
    session_id: str,
    from_record_id: int,
    db_path: Path | None = None,
) -> int:
    """Mark ToolCallRecords as reverted from from_record_id onward.

    Sets status='reverted' on all records for the session with id >= from_record_id.
    Reverted records are excluded from list_tool_call_records() by default and from
    the soc_exporter output, so re-generating the script omits the rolled-back work.

    Args:
        session_id (str): The SoC session whose records should be reverted.
        from_record_id (int): First record ID to mark as reverted (inclusive).
        db_path (Path | None): Override default SQLite DB path.

    Returns:
        int: Number of records marked reverted.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as db_session:
        rows = db_session.exec(
            select(ToolCallRecord)
            .where(ToolCallRecord.session_id == session_id)
            .where(ToolCallRecord.id >= from_record_id)  # type: ignore[operator]
        ).all()
        for row in rows:
            row.status = "reverted"
        db_session.commit()
    return len(rows)

update_plan_checkpoint

update_plan_checkpoint(checkpoint_id: int, *, approved_by_user: bool | None = None, executed: bool | None = None, result_json: str | None = None, rollback_snapshot_id: int | None = None, db_path: Path | None = None) -> None

Patch checkpoint approval/execution fields.

Parameters:

Name	Type	Description	Default
checkpoint_id	int	The checkpoint id value.	required
approved_by_user	bool | None	The approved by user value. Defaults to None.	None
executed	bool | None	The executed value. Defaults to None.	None
result_json	str | None	The result json value. Defaults to None.	None
rollback_snapshot_id	int | None	The rollback snapshot id value. Defaults to None.	None
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Name	Type	Description
None	None	None.

Source code in src/solidworks_mcp/agents/history_db.py

def update_plan_checkpoint(
    checkpoint_id: int,
    *,
    approved_by_user: bool | None = None,
    executed: bool | None = None,
    result_json: str | None = None,
    rollback_snapshot_id: int | None = None,
    db_path: Path | None = None,
) -> None:
    """Patch checkpoint approval/execution fields.

    Args:
        checkpoint_id (int): The checkpoint id value.
        approved_by_user (bool | None): The approved by user value. Defaults to None.
        executed (bool | None): The executed value. Defaults to None.
        result_json (str | None): The result json value. Defaults to None.
        rollback_snapshot_id (int | None): The rollback snapshot id value. Defaults to None.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        None: None.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        row = session.exec(
            select(PlanCheckpoint).where(PlanCheckpoint.id == checkpoint_id)
        ).first()
        if row is None:
            return
        if approved_by_user is not None:
            row.approved_by_user = approved_by_user
        if executed is not None:
            row.executed = executed
        if result_json is not None:
            row.result_json = result_json
        if rollback_snapshot_id is not None:
            row.rollback_snapshot_id = rollback_snapshot_id
        row.updated_at = _utc_now_iso()
        session.add(row)
        session.commit()

update_plan_checkpoint_planned_action

update_plan_checkpoint_planned_action(checkpoint_id: int, *, planned_action_json: str, executed: bool | None = None, result_json: str | None = None, db_path: Path | None = None) -> None

Update checkpoint planned-action JSON and optional execution status.

Parameters:

Name	Type	Description	Default
checkpoint_id	int	Target checkpoint row ID.	required
planned_action_json	str	New planned action payload encoded as JSON string.	required
executed	bool | None	Optional executed flag override.	None
result_json	str | None	Optional result payload override.	None
db_path	Path | None	Optional SQLite path override.	None

Source code in src/solidworks_mcp/agents/history_db.py

def update_plan_checkpoint_planned_action(
    checkpoint_id: int,
    *,
    planned_action_json: str,
    executed: bool | None = None,
    result_json: str | None = None,
    db_path: Path | None = None,
) -> None:
    """Update checkpoint planned-action JSON and optional execution status.

    Args:
        checkpoint_id: Target checkpoint row ID.
        planned_action_json: New planned action payload encoded as JSON string.
        executed: Optional executed flag override.
        result_json: Optional result payload override.
        db_path: Optional SQLite path override.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    with Session(engine) as session:
        row = session.exec(
            select(PlanCheckpoint).where(PlanCheckpoint.id == checkpoint_id)
        ).first()
        if row is None:
            return

        row.planned_action_json = planned_action_json
        if executed is not None:
            row.executed = executed
        if result_json is not None:
            row.result_json = result_json
        row.updated_at = _utc_now_iso()

        session.add(row)
        session.commit()

upsert_design_session

upsert_design_session(*, session_id: str, user_goal: str, source_mode: str = 'model', accepted_family: str | None = None, status: str = 'active', current_checkpoint_index: int = 0, metadata_json: str | None = None, db_path: Path | None = None) -> None

Create or update one interactive design session row.

Parameters:

Name	Type	Description	Default
session_id	str	The session id value.	required
user_goal	str	The user goal value.	required
source_mode	str	The source mode value. Defaults to "model".	'model'
accepted_family	str | None	The accepted family value. Defaults to None.	None
status	str	The status value. Defaults to "active".	'active'
current_checkpoint_index	int	The current checkpoint index value. Defaults to 0.	0
metadata_json	str | None	The metadata json value. Defaults to None.	None
db_path	Path | None	The db path value. Defaults to None.	None

Returns:

Name	Type	Description
None	None	None.

Source code in src/solidworks_mcp/agents/history_db.py

def upsert_design_session(
    *,
    session_id: str,
    user_goal: str,
    source_mode: str = "model",
    accepted_family: str | None = None,
    status: str = "active",
    current_checkpoint_index: int = 0,
    metadata_json: str | None = None,
    db_path: Path | None = None,
) -> None:
    """Create or update one interactive design session row.

    Args:
        session_id (str): The session id value.
        user_goal (str): The user goal value.
        source_mode (str): The source mode value. Defaults to "model".
        accepted_family (str | None): The accepted family value. Defaults to None.
        status (str): The status value. Defaults to "active".
        current_checkpoint_index (int): The current checkpoint index value. Defaults to 0.
        metadata_json (str | None): The metadata json value. Defaults to None.
        db_path (Path | None): The db path value. Defaults to None.

    Returns:
        None: None.
    """
    resolved = init_db(db_path)
    engine = _build_engine(resolved)
    now = _utc_now_iso()
    with Session(engine) as session:
        row = session.exec(
            select(DesignSession).where(DesignSession.session_id == session_id)
        ).first()
        if row is None:
            session.add(
                DesignSession(
                    session_id=session_id,
                    user_goal=user_goal,
                    source_mode=source_mode,
                    accepted_family=accepted_family,
                    status=status,
                    current_checkpoint_index=current_checkpoint_index,
                    metadata_json=metadata_json,
                    created_at=now,
                    updated_at=now,
                )
            )
        else:
            row.user_goal = user_goal
            row.source_mode = source_mode
            row.accepted_family = accepted_family
            row.status = status
            row.current_checkpoint_index = current_checkpoint_index
            row.metadata_json = metadata_json
            row.updated_at = now
            session.add(row)
        session.commit()