sqlserver-semantic-mcp 0.5.0__py3-none-any.whl

sqlserver_semantic_mcp/services/relationship_service.py

@@ -0,0 +1,160 @@
+from typing import Optional
+from collections import deque
+import aiosqlite
+
+from ..infrastructure.cache.structural import read_schema_version
+
+
+_GRAPH_CACHE: dict[tuple[str, str, str], dict[tuple[str, str], list[dict]]] = {}
+
+
+async def get_table_relationships(
+    db_path: str, database: str, schema: str, table: str,
+) -> list[dict]:
+    async with aiosqlite.connect(db_path) as db:
+        db.row_factory = aiosqlite.Row
+        cur = await db.execute(
+            "SELECT schema_name, table_name, column_name, "
+            "       ref_schema, ref_table, ref_column "
+            "FROM sc_foreign_keys "
+            "WHERE database_name=? AND schema_name=? AND table_name=?",
+            (database, schema, table),
+        )
+        outbound = [dict(r) for r in await cur.fetchall()]
+
+        cur = await db.execute(
+            "SELECT schema_name, table_name, column_name, "
+            "       ref_schema, ref_table, ref_column "
+            "FROM sc_foreign_keys "
+            "WHERE database_name=? AND ref_schema=? AND ref_table=?",
+            (database, schema, table),
+        )
+        inbound = [dict(r) for r in await cur.fetchall()]
+
+    results = []
+    for r in outbound:
+        results.append({
+            "direction": "outbound",
+            "from_schema": r["schema_name"], "from_table": r["table_name"],
+            "from_column": r["column_name"],
+            "to_schema": r["ref_schema"], "to_table": r["ref_table"],
+            "to_column": r["ref_column"],
+            "type": "many_to_one",
+        })
+    for r in inbound:
+        results.append({
+            "direction": "inbound",
+            "from_schema": r["schema_name"], "from_table": r["table_name"],
+            "from_column": r["column_name"],
+            "to_schema": r["ref_schema"], "to_table": r["ref_table"],
+            "to_column": r["ref_column"],
+            "type": "one_to_many",
+        })
+    return results
+
+
+async def _load_fk_graph(
+    db_path: str, database: str,
+) -> dict[tuple[str, str], list[dict]]:
+    ver = await read_schema_version(db_path, database)
+    structural_hash = ver["structural_hash"] if ver else ""
+    cache_key = (db_path, database, structural_hash)
+    cached = _GRAPH_CACHE.get(cache_key)
+    if cached is not None:
+        return cached
+
+    graph: dict[tuple[str, str], list[dict]] = {}
+    async with aiosqlite.connect(db_path) as db:
+        db.row_factory = aiosqlite.Row
+        cur = await db.execute(
+            "SELECT schema_name, table_name, column_name, "
+            "       ref_schema, ref_table, ref_column "
+            "FROM sc_foreign_keys WHERE database_name=?",
+            (database,),
+        )
+        for r in await cur.fetchall():
+            src = (r["schema_name"], r["table_name"])
+            dst = (r["ref_schema"], r["ref_table"])
+            graph.setdefault(src, []).append({
+                "from_schema": src[0], "from_table": src[1],
+                "from_column": r["column_name"],
+                "to_schema": dst[0], "to_table": dst[1],
+                "to_column": r["ref_column"],
+                "direction": "outbound",
+            })
+            graph.setdefault(dst, []).append({
+                "from_schema": dst[0], "from_table": dst[1],
+                "from_column": r["ref_column"],
+                "to_schema": src[0], "to_table": src[1],
+                "to_column": r["column_name"],
+                "direction": "inbound",
+            })
+    stale_keys = [
+        key for key in _GRAPH_CACHE
+        if key[:2] == (db_path, database) and key != cache_key
+    ]
+    for key in stale_keys:
+        _GRAPH_CACHE.pop(key, None)
+    _GRAPH_CACHE[cache_key] = graph
+    return graph
+
+
+async def find_join_path(
+    db_path: str, database: str,
+    from_schema: str, from_table: str,
+    to_schema: str, to_table: str,
+    max_hops: int = 5,
+) -> Optional[list[dict]]:
+    graph = await _load_fk_graph(db_path, database)
+    start = (from_schema, from_table)
+    target = (to_schema, to_table)
+    if start == target:
+        return []
+
+    queue = deque([(start, [])])
+    visited = {start}
+    while queue:
+        node, path = queue.popleft()
+        if len(path) >= max_hops:
+            continue
+        for edge in graph.get(node, []):
+            nxt = (edge["to_schema"], edge["to_table"])
+            if nxt in visited:
+                continue
+            new_path = path + [edge]
+            if nxt == target:
+                return new_path
+            visited.add(nxt)
+            queue.append((nxt, new_path))
+    return None
+
+
+async def get_dependency_chain(
+    db_path: str, database: str, schema: str, table: str,
+    max_depth: int = 10,
+    *, schemas: Optional[list[str]] = None,
+) -> list[dict]:
+    graph = await _load_fk_graph(db_path, database)
+    start = (schema, table)
+    visited: dict[tuple[str, str], int] = {start: 0}
+    queue = deque([start])
+    allowed = set(schemas) if schemas else None
+
+    while queue:
+        node = queue.popleft()
+        depth = visited[node]
+        if depth >= max_depth:
+            continue
+        for edge in graph.get(node, []):
+            nxt = (edge["to_schema"], edge["to_table"])
+            if nxt not in visited:
+                if allowed is not None and nxt[0] not in allowed:
+                    continue
+                visited[nxt] = depth + 1
+                queue.append(nxt)
+
+    return [
+        {"schema_name": s, "table_name": t, "depth": d}
+        for (s, t), d in visited.items()
+        if (s, t) != start
+    ]

sqlserver_semantic_mcp/services/semantic_service.py

@@ -0,0 +1,277 @@
+import json
+import re
+from typing import Optional
+import aiosqlite
+
+from ..infrastructure.cache.semantic import (
+    upsert_table_analysis, get_table_analysis,
+)
+from ..infrastructure.cache.structural import read_schema_version
+
+
+_AUDIT_COL_PATTERNS = {
+    "audit_timestamp": re.compile(
+        r"^(created|updated|modified|deleted)(_?at|_?on|_?time|_?date)?$", re.I),
+    "audit_user":      re.compile(
+        r"^(created|updated|modified|deleted)_?by$", re.I),
+    "soft_delete":     re.compile(r"^(is_)?deleted$|^deleted_at$", re.I),
+    "status":          re.compile(r"^(status|state)(_?code|_?id)?$", re.I),
+    "type":            re.compile(r"^(type|category|kind)(_?code|_?id)?$", re.I),
+}
+
+_LOOKUP_NAME_COLS = {"code", "name", "label", "description", "value"}
+
+_COMMON_FILTER_SEMANTICS = frozenset({
+    "status", "type", "audit_timestamp", "soft_delete",
+})
+
+
+async def _load_table_structure(
+    db_path: str, database: str, schema: str, table: str,
+) -> Optional[dict]:
+    async with aiosqlite.connect(db_path) as db:
+        db.row_factory = aiosqlite.Row
+        cur = await db.execute(
+            "SELECT 1 FROM sc_tables WHERE database_name=? "
+            "AND schema_name=? AND table_name=?",
+            (database, schema, table),
+        )
+        if not await cur.fetchone():
+            return None
+
+        cur = await db.execute(
+            "SELECT column_name, data_type, max_length, is_nullable, ordinal_position "
+            "FROM sc_columns WHERE database_name=? AND schema_name=? AND table_name=? "
+            "ORDER BY ordinal_position",
+            (database, schema, table),
+        )
+        columns = [dict(r) for r in await cur.fetchall()]
+
+        cur = await db.execute(
+            "SELECT column_name FROM sc_primary_keys "
+            "WHERE database_name=? AND schema_name=? AND table_name=?",
+            (database, schema, table),
+        )
+        pk = [r["column_name"] for r in await cur.fetchall()]
+
+        cur = await db.execute(
+            "SELECT column_name, ref_schema, ref_table FROM sc_foreign_keys "
+            "WHERE database_name=? AND schema_name=? AND table_name=?",
+            (database, schema, table),
+        )
+        fks = [dict(r) for r in await cur.fetchall()]
+
+    return {"columns": columns, "primary_key": pk, "foreign_keys": fks}
+
+
+def _column_semantic(col: dict) -> Optional[str]:
+    name = col["column_name"]
+    for sem, pat in _AUDIT_COL_PATTERNS.items():
+        if pat.match(name):
+            return sem
+    return None
+
+
+def _classify(struct: dict, table: str) -> dict:
+    cols = struct["columns"]
+    fks = struct["foreign_keys"]
+    col_names = [c["column_name"].lower() for c in cols]
+
+    reasons: list[str] = []
+
+    # Audit heuristic
+    audit_like = sum(1 for c in cols if _column_semantic(c) in (
+        "audit_timestamp", "audit_user"))
+    if audit_like >= 2 and len(cols) <= 6:
+        reasons.append(f"{audit_like} audit-style columns dominate")
+        return {"type": "audit", "confidence": 0.75, "reasons": reasons}
+
+    # Bridge: 2+ FKs and almost all columns are FKs
+    if len(fks) >= 2 and len(cols) <= len(fks) + 2:
+        reasons.append(f"{len(fks)} FKs over {len(cols)} columns")
+        return {"type": "bridge", "confidence": 0.8, "reasons": reasons}
+
+    # Fact: >= 2 FKs
+    if len(fks) >= 2:
+        reasons.append(f"{len(fks)} FKs")
+        return {"type": "fact", "confidence": 0.7, "reasons": reasons}
+
+    # Lookup: few columns, contains code/name-like column names
+    small = len(cols) <= 4
+    lookup_cols = sum(1 for n in col_names if n in _LOOKUP_NAME_COLS)
+    name_suggests_lookup = bool(re.search(
+        r"(status|code|type|category|kind|lookup)$", table, re.I,
+    ))
+    if small and (lookup_cols >= 2 or name_suggests_lookup):
+        reasons.append("small row width + lookup-like columns/name")
+        return {"type": "lookup", "confidence": 0.75, "reasons": reasons}
+
+    # Dimension fallback
+    if len(fks) <= 1 and len(cols) >= 3:
+        reasons.append("few FKs with multiple descriptive columns")
+        return {"type": "dimension", "confidence": 0.5, "reasons": reasons}
+
+    return {"type": "unknown", "confidence": 0.2,
+            "reasons": reasons or ["no rule matched"]}
+
+
+async def classify_table(
+    db_path: str, database: str, schema: str, table: str,
+    *, force: bool = False,
+) -> dict:
+    ver = await read_schema_version(db_path, database)
+    structural_hash = ver["structural_hash"] if ver else ""
+
+    if not force:
+        cached = await get_table_analysis(db_path, database, schema, table)
+        if cached and cached["status"] == "ready" \
+                and cached.get("structural_hash") == structural_hash:
+            return cached["classification"]
+
+    struct = await _load_table_structure(db_path, database, schema, table)
+    if struct is None:
+        return {"type": "unknown", "confidence": 0.0,
+                "reasons": ["table not found"]}
+
+    classification = _classify(struct, table)
+    column_analysis = [
+        {"column": c["column_name"],
+         "semantic_type": _column_semantic(c) or "generic"}
+        for c in struct["columns"]
+    ]
+    is_lookup = classification["type"] == "lookup"
+
+    await upsert_table_analysis(
+        db_path, database, schema, table,
+        structural_hash=structural_hash, status="ready",
+        classification=classification,
+        column_analysis=column_analysis,
+        is_lookup=is_lookup,
+    )
+    return classification
+
+
+async def analyze_columns(
+    db_path: str, database: str, schema: str, table: str,
+) -> list[dict]:
+    await classify_table(db_path, database, schema, table)
+    cached = await get_table_analysis(db_path, database, schema, table)
+    return cached.get("column_analysis", []) if cached else []
+
+
+async def summarize_for_joining(
+    db_path: str, database: str, schema: str, table: str,
+) -> Optional[dict]:
+    """Return reasoning-ready info for joining against this table.
+
+    Shape: {table, pk, classification, join_candidates, common_filter_columns}
+    """
+    struct = await _load_table_structure(db_path, database, schema, table)
+    if struct is None:
+        return None
+
+    join_candidates = [
+        {"via_column": fk["column_name"],
+         "to_table": f"{fk['ref_schema']}.{fk['ref_table']}"}
+        for fk in struct["foreign_keys"]
+    ]
+
+    common_filter_columns = [
+        c["column_name"] for c in struct["columns"]
+        if (_column_semantic(c) or "") in _COMMON_FILTER_SEMANTICS
+    ]
+
+    classification = _classify(struct, table)
+
+    return {
+        "table": f"{schema}.{table}",
+        "pk": struct["primary_key"],
+        "classification": classification["type"],
+        "join_candidates": join_candidates,
+        "common_filter_columns": common_filter_columns,
+    }
+
+
+async def detect_lookup_tables(
+    db_path: str, database: str, *,
+    schemas: Optional[list[str]] = None,
+    keyword: Optional[str] = None,
+    confidence_min: float = 0.0,
+) -> list[dict]:
+    ver = await read_schema_version(db_path, database)
+    current_hash = ver["structural_hash"] if ver else ""
+
+    results: list[dict] = []
+    need_classify: list[tuple[str, str]] = []
+
+    kw_lower = keyword.lower() if keyword else None
+
+    def passes_filter(s: str, t: str) -> bool:
+        if schemas and s not in schemas:
+            return False
+        if kw_lower and kw_lower not in f"{s}.{t}".lower():
+            return False
+        return True
+
+    async with aiosqlite.connect(db_path) as db:
+        db.row_factory = aiosqlite.Row
+        cur = await db.execute(
+            "SELECT schema_name, table_name FROM sc_tables "
+            "WHERE database_name=?",
+            (database,),
+        )
+        all_tables = [(r["schema_name"], r["table_name"])
+                      for r in await cur.fetchall()
+                      if passes_filter(r["schema_name"], r["table_name"])]
+
+        # Fast path: read ready+fresh lookup rows from cache
+        cur = await db.execute(
+            "SELECT schema_name, table_name, classification FROM sem_table_analysis "
+            "WHERE database_name=? AND status='ready' "
+            "AND structural_hash=? AND is_lookup=1",
+            (database, current_hash),
+        )
+        cached_hits = {
+            (r["schema_name"], r["table_name"]):
+                json.loads(r["classification"]) if r["classification"] else None
+            for r in await cur.fetchall()
+        }
+
+        # Tables whose analysis is missing / stale / non-lookup-ready
+        cur = await db.execute(
+            "SELECT schema_name, table_name, status, structural_hash "
+            "FROM sem_table_analysis "
+            "WHERE database_name=?",
+            (database,),
+        )
+        cache_state = {
+            (r["schema_name"], r["table_name"]):
+                (r["status"], r["structural_hash"])
+            for r in await cur.fetchall()
+        }
+
+    for (s, t) in all_tables:
+        if (s, t) in cached_hits:
+            cls = cached_hits[(s, t)] or {"confidence": 0.75}
+            conf = cls.get("confidence", 0.75)
+            if conf >= confidence_min:
+                results.append({
+                    "schema_name": s, "table_name": t,
+                    "confidence": conf,
+                })
+            continue
+        state = cache_state.get((s, t))
+        # Needs classification if: no row, dirty/pending, or hash mismatch
+        if state is None or state[0] != "ready" or state[1] != current_hash:
+            need_classify.append((s, t))
+
+    for (s, t) in need_classify:
+        c = await classify_table(db_path, database, s, t)
+        if c.get("type") == "lookup":
+            conf = c.get("confidence", 0.75)
+            if conf >= confidence_min:
+                results.append({
+                    "schema_name": s, "table_name": t,
+                    "confidence": conf,
+                })
+    return results

sqlserver_semantic_mcp/workflows/__init__.py

@@ -0,0 +1,26 @@
+"""Agent-oriented workflow layer.
+
+Sits between ``server/tools`` and ``services``. Responsible for
+route decision, handoff contracts, context bundling, and the
+direct-execution fast path.
+"""
+from .contracts import ToolEnvelope, RouteDecision, Route
+from .router import route_query
+from .query_flow import plan_or_execute_query
+from .discovery_flow import discover_relevant_tables
+from .bundle import bundle_context_for_next_step
+from .recommendations import suggest_next_tool, estimate_execution_risk
+from .facade import WorkflowFacade
+
+__all__ = [
+    "ToolEnvelope",
+    "RouteDecision",
+    "Route",
+    "route_query",
+    "plan_or_execute_query",
+    "discover_relevant_tables",
+    "bundle_context_for_next_step",
+    "suggest_next_tool",
+    "estimate_execution_risk",
+    "WorkflowFacade",
+]

sqlserver_semantic_mcp/workflows/bundle.py

@@ -0,0 +1,157 @@
+"""Bundle prior tool results into a compact handoff for the next step."""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..config import Config, get_config
+from ..services import metadata_service, object_service, semantic_service
+from ..services.semantic_service import _column_semantic
+from .contracts import ToolEnvelope
+
+
+_JOIN_IMPORTANT = 6
+
+
+async def _table_summary_for_joining(
+    db_path: str, database: str, schema: str, table: str,
+) -> Optional[dict]:
+    full = await metadata_service.describe_table(db_path, database, schema, table)
+    if full is None:
+        return None
+    cls = await semantic_service.classify_table(db_path, database, schema, table)
+    pk = full.get("primary_key", []) or []
+    fks = full.get("foreign_keys", []) or []
+
+    important: list[str] = []
+    seen: set[str] = set()
+
+    def push(name: Optional[str]) -> None:
+        if not name or name in seen:
+            return
+        seen.add(name)
+        important.append(name)
+
+    for col in pk:
+        push(col)
+    for fk in fks:
+        push(fk.get("column_name"))
+    for c in full.get("columns", []):
+        if len(important) >= _JOIN_IMPORTANT:
+            break
+        sem = _column_semantic(c)
+        if sem and sem != "generic":
+            push(c["column_name"])
+    for c in full.get("columns", []):
+        if len(important) >= _JOIN_IMPORTANT:
+            break
+        push(c["column_name"])
+
+    fk_edges = [
+        {
+            "via_column": fk.get("column_name"),
+            "to_table": f"{fk.get('ref_schema')}.{fk.get('ref_table')}",
+            "to_column": fk.get("ref_column"),
+        }
+        for fk in fks
+    ]
+
+    return {
+        "table": f"{schema}.{table}",
+        "classification": cls.get("type", "unknown"),
+        "pk": list(pk),
+        "important_columns": important[:_JOIN_IMPORTANT],
+        "fk_edges": fk_edges,
+    }
+
+
+async def _object_summary_for_impact(
+    schema: str,
+    object_name: str,
+    object_type: str,
+    cfg: Config,
+) -> Optional[dict]:
+    obj = await object_service.describe_object(
+        schema, object_name, object_type, cfg,
+    )
+    if not obj:
+        return None
+    return {
+        "object": f"{schema}.{object_name}",
+        "type": object_type,
+        "reads": list(obj.get("read_tables", []) or []),
+        "writes": list(obj.get("write_tables", []) or []),
+        "depends_on": list(obj.get("dependencies", []) or []),
+        "status": obj.get("status"),
+    }
+
+
+async def bundle_context_for_next_step(
+    items: list[dict],
+    *,
+    goal: str = "joining",
+    detail: str = "brief",
+    cfg: Optional[Config] = None,
+) -> dict:
+    """Compress prior discoveries into the minimum context the next
+    tool needs. Supported goals: ``joining``, ``object_impact``.
+    """
+    cfg = cfg or get_config()
+    db_path = cfg.cache_path
+    database = cfg.mssql_database
+
+    if goal == "joining":
+        tables: list[dict] = []
+        for item in items or []:
+            if item.get("kind") != "table":
+                continue
+            schema = item["schema"]
+            table = item["table"]
+            summary = await _table_summary_for_joining(
+                db_path, database, schema, table,
+            )
+            if summary is not None:
+                tables.append(summary)
+        return ToolEnvelope(
+            kind="bundle_context_for_next_step",
+            detail=detail,
+            next_action="find_or_score_join",
+            recommended_tool="score_join_candidate",
+            bundle_key="joining",
+            data={
+                "bundle_type": "joining",
+                "tables": tables,
+            },
+        ).to_dict()
+
+    if goal == "object_impact":
+        objects: list[dict] = []
+        for item in items or []:
+            if item.get("kind") != "object":
+                continue
+            summary = await _object_summary_for_impact(
+                item["schema"], item["object_name"], item["object_type"], cfg,
+            )
+            if summary is not None:
+                objects.append(summary)
+        return ToolEnvelope(
+            kind="bundle_context_for_next_step",
+            detail=detail,
+            next_action="trace_impact",
+            recommended_tool="trace_object_dependencies",
+            bundle_key="object_impact",
+            data={
+                "bundle_type": "object_impact",
+                "objects": objects,
+            },
+        ).to_dict()
+
+    return ToolEnvelope(
+        kind="bundle_context_for_next_step",
+        detail=detail,
+        next_action="none",
+        data={
+            "bundle_type": goal,
+            "error": f"unsupported goal '{goal}'",
+            "supported_goals": ["joining", "object_impact"],
+        },
+    ).to_dict()

sqlserver_semantic_mcp/workflows/contracts.py

@@ -0,0 +1,64 @@
+"""Handoff contracts for workflow tools.
+
+All workflow tools return structured envelopes so a downstream agent
+knows what to do next without re-parsing payloads.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Optional
+
+
+Route = Literal[
+    "direct_execute",
+    "direct_validate",
+    "discovery",
+    "object_analysis",
+    "policy_only",
+]
+
+
+@dataclass
+class RouteDecision:
+    route: Route
+    reason: str
+    recommended_tools: list[str] = field(default_factory=list)
+    confidence: float = 1.0
+
+    def to_dict(self) -> dict:
+        return {
+            "route": self.route,
+            "reason": self.reason,
+            "recommended_tools": list(self.recommended_tools),
+            "confidence": self.confidence,
+        }
+
+
+@dataclass
+class ToolEnvelope:
+    """Uniform envelope returned by workflow tools.
+
+    ``data`` carries the tool-specific payload. Top-level fields are the
+    agent-visible routing cues.
+    """
+    kind: str
+    detail: str = "brief"
+    confidence: Optional[float] = None
+    next_action: Optional[str] = None
+    recommended_tool: Optional[str] = None
+    bundle_key: Optional[str] = None
+    data: Any = None
+
+    def to_dict(self) -> dict:
+        out: dict[str, Any] = {"kind": self.kind, "detail": self.detail}
+        if self.confidence is not None:
+            out["confidence"] = self.confidence
+        if self.next_action is not None:
+            out["next_action"] = self.next_action
+        if self.recommended_tool is not None:
+            out["recommended_tool"] = self.recommended_tool
+        if self.bundle_key is not None:
+            out["bundle_key"] = self.bundle_key
+        if self.data is not None:
+            out["data"] = self.data
+        return out