Upload 61 files

Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.11
+FROM python:3.10
 
 RUN useradd -m -u 1000 user && python -m pip install --upgrade pip
 USER user

gmatch4py/mcp_output/README_MCP.md

@@ -2,121 +2,127 @@
 
 ## 1) Project Introduction
 
-GMatch4py is a Python library for graph comparison, focused on graph edit distance (GED), graph kernels, and related embedding/matching utilities.  
-This MCP (Model Context Protocol) service wraps core GMatch4py capabilities so LLM clients can compare graphs, compute similarity/distance signals, and use graph-matching outputs in downstream workflows.
+GMatch4py is a Python library for graph comparison and graph kernel computation.  
+This MCP (Model Context Protocol) service wraps GMatch4py capabilities so LLM agents can:
 
-Main capabilities:
-- Graph similarity/distance computation
-- GED-oriented matching workflows
-- Kernel-based graph comparison
-- Integration with NetworkX graph objects
+- Compare two or more graphs
+- Compute graph similarity/distance matrices
+- Run graph edit distance (GED)-style matching workflows
+- Generate kernel/embedding-ready outputs for downstream ML tasks
+
+This is useful for structure-aware retrieval, clustering, anomaly detection, and graph classification pipelines.
 
 ---
 
-## 2) Installation Method
+## 2) Installation
 
 ### Requirements
-- Python 3.x
+
+From repository analysis, core dependencies are:
+
 - numpy
-- scipy
 - networkx
-- Optional: matplotlib (for visualization)
+- scipy
+- scikit-learn
+
+Python package metadata is provided via `setup.py` and `requirements.txt`.
 
 ### Install from source
-1. Clone repository:
-   - https://github.com/Jacobe2169/GMatch4py
+
+1. Clone the repository:
+   git clone https://github.com/Jacobe2169/GMatch4py.git
+
 2. Install dependencies:
-   - pip install -r requirements.txt
-3. Install package:
-   - pip install .
+   pip install -r requirements.txt
+
+3. Install the package:
+   pip install .
 
-If you are building native extensions, ensure your local C/C++ build toolchain is available.
+If you are integrating as an MCP (Model Context Protocol) service, also install your MCP runtime/SDK in the same environment.
 
 ---
 
 ## 3) Quick Start
 
-### Basic Python usage (library side)
-import networkx as nx
-import gmatch4py as gm
+### Python usage (library-level)
 
-g1 = nx.Graph()
-g1.add_edges_from([(1, 2), (2, 3)])
+Typical usage pattern:
 
-g2 = nx.Graph()
-g2.add_edges_from([(1, 2), (2, 4)])
+1. Build or load NetworkX graphs
+2. Initialize a matcher/kernel object from `gmatch4py`
+3. Compute pairwise distances/similarities
+4. Return matrix/results to caller
 
-# Example: choose a matcher/kernel from gmatch4py and compute similarity/distance
-# (Exact class names may vary by version; inspect gm.* modules)
-# matcher = gm.<SomeMatcherOrKernel>(...)
-# result = matcher.compare([g1, g2], None)
+Example flow (conceptual):
 
-print("Graphs loaded and ready for comparison.")
+- Create graph list: `[g1, g2, g3, ...]`
+- Call comparison method (for GED/kernel implementation)
+- Receive NxN matrix for ranking, retrieval, or clustering
 
-### MCP (Model Context Protocol) service usage pattern
-- Start the MCP (Model Context Protocol) service host that exposes GMatch4py operations.
-- Call service tools with:
-  - Graph payload(s) (typically nodes/edges or serialized NetworkX-compatible format)
-  - Algorithm selection (GED/kernel method)
-  - Optional parameters (costs, normalization, etc.)
-- Receive:
-  - Distance/similarity matrix
-  - Pairwise scores
-  - Optional matching metadata
+### MCP (Model Context Protocol) service usage
+
+Typical service flow:
+
+1. Client sends graphs (edge list / adjacency / labeled nodes)
+2. Service validates and normalizes input
+3. Service runs selected algorithm (GED/kernel)
+4. Service returns:
+   - score matrix
+   - pairwise top matches
+   - optional metadata (runtime, parameters)
 
 ---
 
-## 4) Available Tools and Endpoints List
+## 4) Available Tools and Endpoints
+
+Note: this repository does not expose a built-in CLI or MCP server entrypoint by default, so endpoints are typically defined by your wrapper layer. A practical MCP (Model Context Protocol) service should expose tools like:
+
+### `health_check`
+Returns service status, version, dependency availability.
 
-Note: This repository does not define a built-in CLI or explicit HTTP endpoints. In MCP (Model Context Protocol) deployments, expose tools like the following:
+### `list_algorithms`
+Returns supported graph matching/kernel methods and required parameters.
 
-- graph.compare
-  - Compare two or more graphs and return similarity/distance outputs.
-- graph.ged
-  - Run graph edit distance-oriented matching with configurable costs.
-- graph.kernel
-  - Compute kernel-based similarity for graph sets.
-- graph.batch_compare
-  - Run pairwise comparisons for a batch and return matrix-form results.
-- graph.validate
-  - Validate graph input schema/format before computation.
+### `compare_graph_pair`
+Input: two graphs + algorithm settings  
+Output: single similarity/distance score (+ optional alignment details).
 
-Recommended input fields:
-- graphs: list of graph objects (nodes/edges/attributes)
-- method: GED or kernel method name
-- options: algorithm-specific parameters
-- return_metadata: boolean for detailed diagnostics
+### `compare_graph_batch`
+Input: list of graphs + algorithm settings  
+Output: pairwise matrix, optional nearest-neighbor list.
+
+### `compute_kernel_matrix`
+Input: graph set + kernel config  
+Output: kernel/similarity matrix suitable for ML models.
+
+### `embed_graphs` (optional)
+Input: graph set + embedding config  
+Output: vector representation per graph.
+
+### `explain_score` (optional)
+Input: graph pair + prior score context  
+Output: human-readable explanation of similarity/difference drivers.
 
 ---
 
 ## 5) Common Issues and Notes
 
-- Build/install issues:
-  - If installation fails, verify compiler/build tools and matching Python headers are installed.
-- Dependency mismatches:
-  - Keep numpy/scipy/networkx versions consistent in your environment.
-- Input format errors:
-  - Ensure graph payloads are structurally valid and consistent across batch calls.
-- Performance:
-  - GED can be expensive on large/dense graphs; prefer batch sizing, caching, or kernel approximations when needed.
-- Environment:
-  - Use a virtual environment to avoid package conflicts.
-- Testing:
-  - Repository includes tests under `test/`; run them after installation to validate behavior.
+- No native MCP server included: you need a thin wrapper that maps MCP tools to `gmatch4py` calls.
+- Dependency compatibility: use a clean virtual environment to avoid SciPy / scikit-learn version conflicts.
+- Input format consistency: enforce a single graph schema (node IDs, labels, edge attributes).
+- Performance: pairwise comparison scales roughly with graph count² for full matrices; use batching/caching for large sets.
+- Reproducibility: pin versions in `requirements.txt`/lockfile and log algorithm parameters per request.
+- Build concerns: package uses `setup.py`; if wheels fail, install compiler/build essentials and retry.
 
 ---
 
-## 6) Reference Links and Documentation
+## 6) References
 
 - Repository: https://github.com/Jacobe2169/GMatch4py
-- Existing project README (source of algorithm usage details):  
-  https://github.com/Jacobe2169/GMatch4py/blob/master/README.md
-- Python packaging files:
-  - `requirements.txt`
-  - `setup.py`
-- Related dependency docs:
-  - https://networkx.org/
-  - https://numpy.org/
-  - https://scipy.org/
-
-If you are packaging this as an MCP (Model Context Protocol) service, add your host-specific transport/config docs (stdio/SSE/WebSocket), tool schemas, and example request/response payloads alongside this README.
+- Package metadata: `setup.py`
+- Dependencies: `requirements.txt`
+- Tests/examples:
+  - `test/test.py`
+  - `test/gmatch4py_performance_test.py`
+
+If you are deploying this as an MCP (Model Context Protocol) service, keep service contracts (input schema, output schema, error model) documented alongside this README.

gmatch4py/mcp_output/analysis.json

@@ -42,6 +42,8 @@
   },
   "structure": {
     "packages": [
+      "deployment.gmatch4py.source",
+      "mcp_output.mcp_plugin",
       "source.gmatch4py",
       "source.gmatch4py.embedding",
       "source.gmatch4py.ged",
@@ -93,14 +95,13 @@
       "required": [
         "numpy",
         "networkx",
-        "scipy"
+        "scipy",
+        "scikit-learn"
       ],
-      "optional": [
-        "matplotlib"
-      ]
+      "optional": []
     },
     "risk_assessment": {
-      "import_feasibility": 0.86,
+      "import_feasibility": 0.63,
       "intrusiveness_risk": "low",
       "complexity": "medium"
     }
@@ -118,7 +119,7 @@
     "model": "gpt-5.3-codex"
   },
   "risk": {
-    "import_feasibility": 0.86,
+    "import_feasibility": 0.63,
     "intrusiveness_risk": "low",
     "complexity": "medium"
   }

gmatch4py/mcp_output/diff_report.md

@@ -1,143 +1,163 @@
-# Difference Report — **GMatch4py**
+# GMatch4py — Difference Report
 
-**Generated:** 2026-03-12 11:48:23  
+**Generated:** 2026-03-14 21:54:20  
 **Repository:** `GMatch4py`  
 **Project Type:** Python library  
-**Scope:** Basic functionality  
-**Change Intrusiveness:** None (additive only)  
+**Change Scope:** Basic functionality  
+**Intrusiveness:** None  
 **Workflow Status:** ✅ Success  
 **Test Status:** ❌ Failed  
-**Files Changed:** 8 new, 0 modified
+**File Summary:** 8 new files, 0 modified files
 
 ---
 
 ## 1) Project Overview
 
-This update introduces **new files only** and does not modify existing code, indicating a low-risk, additive change pattern.  
-Although CI/workflow execution completed successfully, tests are currently failing, which blocks confidence in release readiness.
+This update introduces **new foundational components** to the `GMatch4py` Python library without altering existing files. The change set appears to focus on enabling or scaffolding **basic functionality** while preserving prior code paths (no in-place modifications).
+
+Because all changes are additive, backward compatibility risk is generally low at the source level, but runtime and packaging behavior still require validation due to failing tests.
 
 ---
 
-## 2) Change Summary
+## 2) Difference Summary
 
-| Metric | Value |
-|---|---|
-| New files | 8 |
-| Modified files | 0 |
-| Deleted files | 0 (not reported) |
-| Intrusiveness | None |
-| Functional impact | Likely additive / non-breaking by design |
-| Validation outcome | Workflow passed, tests failed |
+## High-level delta
+- **Added:** 8 files  
+- **Modified:** 0 files  
+- **Deleted:** 0 files (not reported)
 
-### High-level interpretation
-- The change set appears structurally safe (no edits to established logic).
-- Test failure suggests one or more of:
-  - New files introduced test cases failing against current behavior.
-  - Environment/config mismatch in test stage.
-  - Missing integration/registration of newly added components.
+## Interpretation
+- The update is likely a **feature bootstrap** or **initial module expansion**.
+- No existing behavior was directly edited, suggesting a conservative integration strategy.
+- However, failed tests indicate either:
+  - Missing integration wiring,
+  - Environment/dependency mismatch,
+  - Incomplete implementation of newly added functionality, or
+  - Test suite drift/incompatibility.
 
 ---
 
-## 3) Difference Analysis
+## 3) Technical Analysis
+
+## 3.1 Change Characteristics
+- **Intrusiveness: None** implies no invasive refactors or broad architectural rewrites.
+- Additive-only change sets are generally easier to review and rollback.
+- Risk centers around:
+  - Import graph changes from new modules,
+  - Package exposure (`__init__.py`, setup metadata),
+  - New dependency declarations and version constraints,
+  - Runtime assumptions introduced by new code.
+
+## 3.2 CI/Workflow Signals
+- **Workflow success + tests failed** suggests:
+  - Pipeline infrastructure ran correctly,
+  - Build/lint/package stages may be passing,
+  - Functional correctness gates are currently blocking release readiness.
+
+## 3.3 Likely Failure Domains (for basic functionality additions)
+1. **Unit tests not aligned** with newly added modules/APIs.
+2. **Missing fixtures/mocks** for new behavior.
+3. **Version conflicts** in dependency resolution.
+4. **Public API exposure gaps** (new code exists but not imported/exported).
+5. **Edge-case handling** unimplemented in initial feature scaffolding.
+
+---
 
-## What changed
-- **8 newly added files** were introduced to the repository.
-- **No existing files modified**, minimizing regression risk in legacy paths.
+## 4) Quality & Risk Assessment
 
-## What this implies
-- Backward compatibility is likely preserved at code-edit level.
-- Failures are probably tied to:
-  - New feature expectations not yet implemented end-to-end.
-  - Packaging/import path issues for newly introduced modules.
-  - Test assumptions that differ from current runtime configuration.
+| Area | Status | Risk |
+|---|---|---|
+| Build/Workflow execution | Passing | Low |
+| Functional test validation | Failing | High |
+| Backward compatibility (code modifications) | Favorable (no modified files) | Low-Medium |
+| Release readiness | Not ready | High |
+
+**Overall:** The update is structurally safe but **not production-ready** until test failures are resolved.
 
 ---
 
-## 4) Technical Analysis
+## 5) Recommendations & Improvements
 
-## CI/Workflow
-- **Workflow status: success** indicates pipeline orchestration, install, and stage execution were operational.
+## Immediate actions (P0)
+1. **Triage failing tests**
+   - Categorize by failure type: import, assertion, integration, environment.
+   - Identify whether failures are in legacy tests vs. tests for new files.
 
-## Test Layer
-- **Test status: failed** indicates quality gate not met.
-- Since only new files were added, likely failure categories:
-  1. **Discovery/collection errors** (e.g., bad imports, missing dependencies).
-  2. **Contract mismatch** (tests expect outputs/behavior not implemented).
-  3. **Fixture/config drift** (paths, environment variables, optional libs absent).
+2. **Validate package integration**
+   - Ensure new modules are discoverable and properly exported.
+   - Confirm setup/pyproject includes new files and dependencies.
 
-## Risk Profile
-- **Code-change risk:** Low (no existing logic touched).
-- **Release risk:** Medium to High until failing tests are resolved.
-- **Operational risk:** Low for existing consumers if unreleased; unknown if released with failing tests.
+3. **Reproduce failures locally and in CI**
+   - Pin Python version and dependency lock state.
+   - Compare local/CI test matrices for divergence.
 
----
+## Near-term actions (P1)
+4. **Add/adjust tests for added files**
+   - Cover happy path + minimal edge cases for basic functionality.
+   - Include negative tests for invalid inputs.
 
-## 5) Quality & Compliance Assessment
+5. **Documentation sync**
+   - Add concise usage examples for new features.
+   - Document any newly required dependencies/configuration.
 
-- ✅ Additive change strategy aligns with low-intrusion principle.
-- ⚠️ Failed tests violate standard release quality threshold.
-- ⚠️ Missing detailed diff artifact (file list and per-file intent) limits traceability.
+6. **Quality gates**
+   - Enforce pass criteria: unit tests, type checks (if used), lint checks, coverage threshold.
 
----
+## Medium-term actions (P2)
+7. **Stabilization pass**
+   - Improve error messages and exception taxonomy.
+   - Add regression tests for each resolved failure.
 
-## 6) Recommendations & Improvements
-
-## Immediate (P0)
-1. **Triage failing tests from CI logs**
-   - Classify into import/config/logic failures.
-2. **Reproduce locally using CI-equivalent environment**
-   - Pin Python version and dependency set used in pipeline.
-3. **Block release until test suite is green**
-   - Enforce required status checks.
-
-## Near-term (P1)
-1. **Add/adjust smoke tests** for newly added files.
-2. **Improve failure diagnostics**
-   - Enable verbose pytest output (`-vv`), durations, and traceback shortening controls.
-3. **Document new files’ purpose**
-   - Changelog entry + module-level README updates.
-
-## Process (P2)
-1. **Adopt diff checklist in PR template**
-   - “New files registered?”, “Imports valid?”, “Tests added and passing?”
-2. **Strengthen CI matrix**
-   - Multiple Python versions and minimal/max dependency ranges.
+8. **Release checklist hardening**
+   - Introduce pre-merge test matrix for supported Python versions.
+   - Add smoke tests for installation and importability.
 
 ---
 
-## 7) Deployment Information
+## 6) Deployment Information
+
+## Current deployability
+- **Not recommended for production deployment** due to failed tests.
+
+## Suggested deployment strategy
+- Keep changes in a feature/staging branch.
+- Gate promotion with:
+  - 100% pass on critical test subset,
+  - No unresolved dependency conflicts,
+  - Verified wheel/sdist installation test.
 
-## Current deployment readiness
-- **Not release-ready** due to failing tests.
+## Rollback considerations
+- Since changes are additive (0 modified files), rollback is straightforward:
+  - Revert the 8 new files in a single revert commit if needed.
+
+---
 
-## Suggested deployment decision
-- **Hold deployment**.
-- Proceed only after:
-  - All tests pass.
-  - New files are verified in package build/artifacts.
-  - Basic runtime sanity check passes (import + minimal usage path).
+## 7) Future Planning
 
-## Rollout guidance (post-fix)
-- Use a **patch/minor release** depending on whether new files expose new public API.
-- Include release notes explicitly stating additive scope.
+1. **Complete basic functionality milestone**
+   - Define clear acceptance criteria for the newly introduced modules.
+2. **Expand test depth**
+   - Add integration tests validating module interoperability.
+3. **API stabilization**
+   - Mark experimental interfaces if signatures may still evolve.
+4. **Performance baseline (optional)**
+   - Capture initial runtime benchmarks for future regression tracking.
+5. **Versioning discipline**
+   - Release as pre-minor/patch according to semantic impact after tests pass.
 
 ---
 
-## 8) Future Planning
+## 8) Suggested Next-Step Checklist
 
-1. **Stabilize baseline**
-   - Resolve current failures and capture root-cause postmortem.
-2. **Expand regression coverage**
-   - Add tests around new-file integration points.
-3. **Improve observability in CI**
-   - Publish junit+xml and coverage artifacts for quicker diagnosis.
-4. **Formalize release gates**
-   - Require green tests + packaging check + lint/type checks.
+- [ ] Identify all failing test cases and root causes  
+- [ ] Fix import/export and dependency issues for new files  
+- [ ] Add missing unit tests for basic functionality  
+- [ ] Re-run full CI matrix and confirm green status  
+- [ ] Update docs/changelog for new additions  
+- [ ] Approve release only after test pass and packaging validation
 
 ---
 
 ## 9) Executive Conclusion
 
-The GMatch4py update is structurally low-intrusive (**8 new files, no modifications**), but **test failures currently block production confidence**.  
-From a governance perspective: **safe change pattern, insufficient validation outcome**.  
-Recommended action: **fix test failures, re-run CI, then release with documented additive scope**.
+This change set is a **non-intrusive, additive update** introducing basic capabilities into `GMatch4py`. While workflow execution is healthy, **test failures are a release blocker**. Resolve test issues, validate integration, and complete minimal documentation before considering deployment.

gmatch4py/mcp_output/mcp_plugin/adapter.py

@@ -2,294 +2,363 @@ import os
 import sys
 import traceback
 import importlib
+import inspect
 from typing import Any, Dict, List, Optional
 
-source_path = os.path.join(
-    os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))),
-    "source",
-)
+source_path = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))), "source")
 sys.path.insert(0, source_path)
 
 
 class Adapter:
     """
-    Import-mode adapter for the GMatch4py repository.
+    MCP Import-mode adapter for the GMatch4py repository.
 
-    This adapter attempts to import and expose repository-level functionality
-    discovered during analysis, with graceful fallback behavior when imports fail.
+    This adapter attempts to import repository modules directly from the local
+    `source` directory and exposes unified wrapper methods for discovered
+    functions and classes.
 
-    Key features:
-    - Import mode with fallback-safe execution
-    - Unified return schema for all methods
-    - Function-level wrappers for discovered callable entries
-    - Helpful, actionable English-only error messages
+    Unified return format:
+        {
+            "status": "success" | "error" | "fallback",
+            "mode": "import",
+            "message": str,
+            ... extra fields ...
+        }
     """
 
     # -------------------------------------------------------------------------
     # Initialization and module management
     # -------------------------------------------------------------------------
     def __init__(self) -> None:
-        """
-        Initialize the adapter in import mode and attempt to load target modules.
-
-        Attributes:
-            mode (str): Adapter running mode, fixed as "import".
-            loaded (bool): Whether required modules were loaded successfully.
-            modules (dict): Cached imported modules keyed by logical name.
-            errors (list): Captured import-time errors.
-        """
         self.mode = "import"
-        self.loaded = False
-        self.modules: Dict[str, Any] = {}
-        self.errors: List[str] = []
-        self._load_modules()
-
-    def _result(
-        self,
-        status: str,
-        message: str,
-        data: Optional[Dict[str, Any]] = None,
-        error: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        return {
-            "status": status,
-            "mode": self.mode,
-            "message": message,
-            "data": data or {},
-            "error": error,
-        }
+        self.repo_name = "GMatch4py"
+        self.repo_url = "https://github.com/Jacobe2169/GMatch4py"
+        self.import_strategy = {"primary": "import", "fallback": "blackbox", "confidence": 0.9}
+        self.required_dependencies = ["numpy", "networkx", "scipy", "scikit-learn"]
 
-    def _load_modules(self) -> None:
-        """
-        Load known modules discovered by analysis.
+        self.modules: Dict[str, Optional[Any]] = {}
+        self.symbols: Dict[str, Optional[Any]] = {}
+        self.last_error: Optional[str] = None
 
-        The analysis identified:
-        - package: setup
-        - module: setup
-        - functions: makeExtension, scandir
+        self._initialize_imports()
 
-        Also attempts optional package imports for repository subpackages to
-        maximize utility and diagnosability.
-        """
-        required_imports = {
-            "setup": "setup",
-        }
-        optional_imports = {
-            "gmatch4py": "gmatch4py",
-            "embedding": "gmatch4py.embedding",
-            "ged": "gmatch4py.ged",
-            "helpers": "gmatch4py.helpers",
-            "kernels": "gmatch4py.kernels",
-        }
+    def _result(self, status: str, message: str, **kwargs: Any) -> Dict[str, Any]:
+        data = {"status": status, "mode": self.mode, "message": message}
+        data.update(kwargs)
+        return data
 
-        for key, module_path in required_imports.items():
-            try:
-                self.modules[key] = importlib.import_module(module_path)
-            except Exception as exc:
-                self.errors.append(
-                    f"Failed to import required module '{module_path}'. "
-                    f"Verify repository source is present under 'source/' and dependencies are installed. "
-                    f"Original error: {exc}"
-                )
+    def _safe_import_module(self, module_path: str) -> Dict[str, Any]:
+        try:
+            module = importlib.import_module(module_path)
+            self.modules[module_path] = module
+            return self._result("success", f"Imported module '{module_path}' successfully.", module_path=module_path)
+        except Exception as e:
+            self.modules[module_path] = None
+            err = f"Failed to import module '{module_path}': {e}"
+            self.last_error = err
+            return self._result(
+                "fallback",
+                err + " Verify local source files and Python dependencies are available.",
+                module_path=module_path,
+                error=str(e),
+            )
 
-        for key, module_path in optional_imports.items():
-            try:
-                self.modules[key] = importlib.import_module(module_path)
-            except Exception:
-                pass
+    def _safe_get_symbol(self, module_path: str, symbol_name: str) -> Dict[str, Any]:
+        module = self.modules.get(module_path)
+        if module is None:
+            return self._result(
+                "fallback",
+                f"Module '{module_path}' is not available. Import the module before requesting symbol '{symbol_name}'.",
+                module_path=module_path,
+                symbol_name=symbol_name,
+            )
+        try:
+            symbol = getattr(module, symbol_name)
+            self.symbols[f"{module_path}.{symbol_name}"] = symbol
+            return self._result(
+                "success",
+                f"Loaded symbol '{symbol_name}' from '{module_path}'.",
+                module_path=module_path,
+                symbol_name=symbol_name,
+            )
+        except Exception as e:
+            err = f"Failed to load symbol '{symbol_name}' from '{module_path}': {e}"
+            self.last_error = err
+            self.symbols[f"{module_path}.{symbol_name}"] = None
+            return self._result(
+                "fallback",
+                err + " Confirm repository version contains this symbol.",
+                module_path=module_path,
+                symbol_name=symbol_name,
+                error=str(e),
+            )
+
+    def _initialize_imports(self) -> None:
+        target_modules = [
+            "gmatch4py",
+            "gmatch4py.embedding",
+            "gmatch4py.ged",
+            "gmatch4py.helpers",
+            "gmatch4py.kernels",
+            "setup",
+        ]
+        for module_path in target_modules:
+            self._safe_import_module(module_path)
 
-        self.loaded = "setup" in self.modules
+        # Discovered functions from analysis: setup.makeExtension, setup.scandir
+        self._safe_get_symbol("setup", "makeExtension")
+        self._safe_get_symbol("setup", "scandir")
 
     # -------------------------------------------------------------------------
-    # Status and diagnostics
+    # Health and diagnostics
     # -------------------------------------------------------------------------
     def health_check(self) -> Dict[str, Any]:
         """
-        Check adapter readiness and module availability.
+        Perform a basic health check for import-mode readiness.
 
         Returns:
-            dict: Unified status payload with loaded modules and import diagnostics.
+            dict: Unified status payload including module availability and
+                  discovered symbols.
         """
-        if self.loaded:
+        module_status = {k: (v is not None) for k, v in self.modules.items()}
+        symbol_status = {k: (v is not None) for k, v in self.symbols.items()}
+        all_core_ok = module_status.get("setup", False) and symbol_status.get("setup.makeExtension", False)
+
+        if all_core_ok:
             return self._result(
-                status="success",
-                message="Adapter is ready in import mode.",
-                data={
-                    "loaded": True,
-                    "loaded_modules": sorted(list(self.modules.keys())),
-                    "import_errors": self.errors,
-                },
+                "success",
+                "Adapter is ready in import mode.",
+                repository=self.repo_name,
+                repository_url=self.repo_url,
+                modules=module_status,
+                symbols=symbol_status,
+                dependencies=self.required_dependencies,
             )
+
         return self._result(
-            status="error",
-            message=(
-                "Adapter is not fully ready. Required modules failed to import. "
-                "Ensure the repository exists under 'source/' and install dependencies: numpy, networkx, scipy."
-            ),
-            data={
-                "loaded": False,
-                "loaded_modules": sorted(list(self.modules.keys())),
-                "import_errors": self.errors,
-            },
-            error="Required import failure",
+            "fallback",
+            "Adapter initialized with partial imports. Install missing dependencies and verify source layout.",
+            repository=self.repo_name,
+            repository_url=self.repo_url,
+            modules=module_status,
+            symbols=symbol_status,
+            dependencies=self.required_dependencies,
+            last_error=self.last_error,
         )
 
+    def list_available_symbols(self) -> Dict[str, Any]:
+        """
+        List currently loaded callable/class symbols discovered by the adapter.
+
+        Returns:
+            dict: Unified status payload with symbol metadata.
+        """
+        available = []
+        for fq_name, sym in self.symbols.items():
+            if sym is None:
+                continue
+            available.append(
+                {
+                    "name": fq_name,
+                    "type": "class" if inspect.isclass(sym) else "function" if callable(sym) else type(sym).__name__,
+                    "signature": str(inspect.signature(sym)) if callable(sym) else None,
+                }
+            )
+        return self._result("success", "Collected available symbols.", symbols=available, count=len(available))
+
     # -------------------------------------------------------------------------
-    # Function wrappers (discovered via analysis): setup.makeExtension
+    # Function wrappers discovered from LLM analysis
     # -------------------------------------------------------------------------
-    def call_makeExtension(
-        self,
-        ext_name: str,
-        file_path: str,
-    ) -> Dict[str, Any]:
+    def call_setup_makeExtension(self, ext_name: str, file_path: str) -> Dict[str, Any]:
         """
-        Call setup.makeExtension(ext_name, file_path) from repository setup module.
+        Call setup.makeExtension(ext_name, file_path).
 
         Parameters:
-            ext_name (str): Extension module name expected by setup helper.
-            file_path (str): Relative or absolute path used by the setup helper.
+            ext_name (str): Extension name to build.
+            file_path (str): File path used by setup logic.
 
         Returns:
-            dict: Unified status response containing call output under data.result.
+            dict: Unified status payload containing function result.
         """
-        if not self.loaded:
+        fn = self.symbols.get("setup.makeExtension")
+        if fn is None:
             return self._result(
-                status="error",
-                message=(
-                    "Import mode is unavailable because required modules could not be loaded. "
-                    "Run health_check() and fix import issues first."
-                ),
-                error="Adapter not ready",
+                "fallback",
+                "Function 'setup.makeExtension' is unavailable. Ensure 'source/setup.py' exists and imports cleanly.",
+                function="setup.makeExtension",
             )
-
-        setup_mod = self.modules.get("setup")
-        if setup_mod is None or not hasattr(setup_mod, "makeExtension"):
+        try:
+            result = fn(ext_name, file_path)
+            return self._result(
+                "success",
+                "Function 'setup.makeExtension' executed successfully.",
+                function="setup.makeExtension",
+                inputs={"ext_name": ext_name, "file_path": file_path},
+                result=result,
+            )
+        except Exception as e:
             return self._result(
-                status="error",
-                message=(
-                    "Function 'makeExtension' is not available in module 'setup'. "
-                    "Check repository version compatibility."
-                ),
-                error="Missing function",
+                "error",
+                "Execution failed for 'setup.makeExtension'. Validate parameters and repository compatibility.",
+                function="setup.makeExtension",
+                error=str(e),
+                traceback=traceback.format_exc(),
             )
 
+    def call_setup_scandir(self, directory: str, files: Optional[List[str]] = None) -> Dict[str, Any]:
+        """
+        Call setup.scandir(directory, files=None).
+
+        Parameters:
+            directory (str): Root directory to scan.
+            files (list[str], optional): Pre-populated collector list.
+
+        Returns:
+            dict: Unified status payload containing function result.
+        """
+        fn = self.symbols.get("setup.scandir")
+        if fn is None:
+            return self._result(
+                "fallback",
+                "Function 'setup.scandir' is unavailable. Ensure 'source/setup.py' exists and imports cleanly.",
+                function="setup.scandir",
+            )
         try:
-            result = setup_mod.makeExtension(ext_name, file_path)
+            if files is None:
+                result = fn(directory)
+                call_args = {"directory": directory}
+            else:
+                result = fn(directory, files)
+                call_args = {"directory": directory, "files": files}
             return self._result(
-                status="success",
-                message="Function 'makeExtension' executed successfully.",
-                data={"result": result},
+                "success",
+                "Function 'setup.scandir' executed successfully.",
+                function="setup.scandir",
+                inputs=call_args,
+                result=result,
             )
-        except Exception as exc:
+        except Exception as e:
             return self._result(
-                status="error",
-                message=(
-                    "Execution of 'makeExtension' failed. "
-                    "Validate ext_name and file_path inputs and ensure setup configuration is valid."
-                ),
-                error=f"{exc}\n{traceback.format_exc()}",
+                "error",
+                "Execution failed for 'setup.scandir'. Verify directory path and access permissions.",
+                function="setup.scandir",
+                error=str(e),
+                traceback=traceback.format_exc(),
             )
 
     # -------------------------------------------------------------------------
-    # Function wrappers (discovered via analysis): setup.scandir
+    # Generic module-level helpers for extension and fallback usability
     # -------------------------------------------------------------------------
-    def call_scandir(
-        self,
-        directory: str,
-        files: Optional[List[str]] = None,
-    ) -> Dict[str, Any]:
+    def call_module_function(self, module_path: str, function_name: str, *args: Any, **kwargs: Any) -> Dict[str, Any]:
         """
-        Call setup.scandir(directory, files) from repository setup module.
+        Generic dynamic function caller.
 
         Parameters:
-            directory (str): Directory path to recursively scan.
-            files (list[str], optional): Existing accumulator list used by the original function.
+            module_path (str): Full module path (e.g., 'gmatch4py.kernels').
+            function_name (str): Target function name.
+            *args: Positional arguments.
+            **kwargs: Keyword arguments.
 
         Returns:
-            dict: Unified status response containing scan result under data.result.
+            dict: Unified status payload with execution result.
         """
-        if not self.loaded:
+        if module_path not in self.modules or self.modules[module_path] is None:
+            import_result = self._safe_import_module(module_path)
+            if import_result["status"] not in ("success",):
+                return import_result
+
+        module = self.modules[module_path]
+        try:
+            fn = getattr(module, function_name)
+        except Exception as e:
             return self._result(
-                status="error",
-                message=(
-                    "Import mode is unavailable because required modules could not be loaded. "
-                    "Run health_check() and fix import issues first."
-                ),
-                error="Adapter not ready",
+                "fallback",
+                f"Function '{function_name}' not found in module '{module_path}'. Check the repository API version.",
+                module_path=module_path,
+                function_name=function_name,
+                error=str(e),
             )
 
-        setup_mod = self.modules.get("setup")
-        if setup_mod is None or not hasattr(setup_mod, "scandir"):
+        if not callable(fn):
             return self._result(
-                status="error",
-                message=(
-                    "Function 'scandir' is not available in module 'setup'. "
-                    "Check repository version compatibility."
-                ),
-                error="Missing function",
+                "error",
+                f"Symbol '{function_name}' in '{module_path}' is not callable.",
+                module_path=module_path,
+                function_name=function_name,
             )
 
-        if files is None:
-            files = []
-
         try:
-            result = setup_mod.scandir(directory, files)
+            result = fn(*args, **kwargs)
             return self._result(
-                status="success",
-                message="Function 'scandir' executed successfully.",
-                data={"result": result},
+                "success",
+                f"Function '{module_path}.{function_name}' executed successfully.",
+                module_path=module_path,
+                function_name=function_name,
+                result=result,
             )
-        except Exception as exc:
+        except Exception as e:
             return self._result(
-                status="error",
-                message=(
-                    "Execution of 'scandir' failed. "
-                    "Ensure 'directory' exists and is readable, and 'files' is a list."
-                ),
-                error=f"{exc}\n{traceback.format_exc()}",
+                "error",
+                f"Execution failed for '{module_path}.{function_name}'.",
+                module_path=module_path,
+                function_name=function_name,
+                error=str(e),
+                traceback=traceback.format_exc(),
             )
 
-    # -------------------------------------------------------------------------
-    # Package access helpers (graceful fallback utilities)
-    # -------------------------------------------------------------------------
-    def get_package_info(self) -> Dict[str, Any]:
+    def create_class_instance(self, module_path: str, class_name: str, *args: Any, **kwargs: Any) -> Dict[str, Any]:
         """
-        Return package-level import information for discovered gmatch4py modules.
+        Generic dynamic class instantiation helper.
+
+        Parameters:
+            module_path (str): Full module path.
+            class_name (str): Name of class to instantiate.
+            *args: Positional constructor args.
+            **kwargs: Keyword constructor args.
 
         Returns:
-            dict: Unified status response including available package modules.
+            dict: Unified status payload with instance or error details.
         """
-        available = {
-            k: v.__name__
-            for k, v in self.modules.items()
-            if k in {"gmatch4py", "embedding", "ged", "helpers", "kernels"}
-        }
-        return self._result(
-            status="success",
-            message="Collected package import information.",
-            data={
-                "available_packages": available,
-                "required_ready": self.loaded,
-                "import_errors": self.errors,
-            },
-        )
+        if module_path not in self.modules or self.modules[module_path] is None:
+            import_result = self._safe_import_module(module_path)
+            if import_result["status"] not in ("success",):
+                return import_result
 
-    def fallback_guidance(self) -> Dict[str, Any]:
-        """
-        Provide actionable fallback guidance when import mode is partially unavailable.
+        module = self.modules[module_path]
+        try:
+            cls = getattr(module, class_name)
+        except Exception as e:
+            return self._result(
+                "fallback",
+                f"Class '{class_name}' not found in module '{module_path}'. Confirm API availability.",
+                module_path=module_path,
+                class_name=class_name,
+                error=str(e),
+            )
 
-        Returns:
-            dict: Unified status response with practical troubleshooting steps.
-        """
-        guidance = [
-            "Ensure the repository root contains a 'source/' directory with GMatch4py files.",
-            "Install required dependencies: numpy, networkx, scipy.",
-            "Optional dependency for plotting: matplotlib.",
-            "Verify Python can import 'setup' from the repository source path.",
-            "Use health_check() to inspect current import status and error details.",
-        ]
-        return self._result(
-            status="success",
-            message="Fallback guidance generated.",
-            data={"steps": guidance, "import_errors": self.errors},
-        )
+        if not inspect.isclass(cls):
+            return self._result(
+                "error",
+                f"Symbol '{class_name}' in '{module_path}' is not a class.",
+                module_path=module_path,
+                class_name=class_name,
+            )
+
+        try:
+            instance = cls(*args, **kwargs)
+            return self._result(
+                "success",
+                f"Class '{module_path}.{class_name}' instantiated successfully.",
+                module_path=module_path,
+                class_name=class_name,
+                instance=instance,
+            )
+        except Exception as e:
+            return self._result(
+                "error",
+                f"Failed to instantiate '{module_path}.{class_name}'. Check constructor arguments.",
+                module_path=module_path,
+                class_name=class_name,
+                error=str(e),
+                traceback=traceback.format_exc(),
+            )

gmatch4py/mcp_output/requirements.txt

@@ -7,3 +7,4 @@ scipy
 networkx==2.1
 numpy
 cython
+scikit-learn

gmatch4py/mcp_output/workflow_summary.json

@@ -14,9 +14,9 @@
     "intrusiveness_risk": "low"
   },
   "execution": {
-    "start_time": 1773286984.0154939,
-    "end_time": 1773287160.033365,
-    "duration": 176.01787114143372,
+    "start_time": 1773496171.444042,
+    "end_time": 1773496341.4492779,
+    "duration": 170.00523591041565,
     "status": "success",
     "workflow_status": "success",
     "nodes_executed": [
@@ -28,7 +28,7 @@
       "review",
       "finalize"
     ],
-    "total_files_processed": 5,
+    "total_files_processed": 7,
     "environment_type": "unknown",
     "llm_calls": 0,
     "deepwiki_calls": 0
@@ -54,6 +54,8 @@
   "analysis": {
     "structure": {
       "packages": [
+        "deployment.gmatch4py.source",
+        "mcp_output.mcp_plugin",
         "source.gmatch4py",
         "source.gmatch4py.embedding",
         "source.gmatch4py.ged",
@@ -74,7 +76,7 @@
       "modules": []
     },
     "risk_assessment": {
-      "import_feasibility": 0.86,
+      "import_feasibility": 0.63,
       "intrusiveness_risk": "low",
       "complexity": "medium"
     },
@@ -130,34 +132,31 @@
   "errors": [],
   "warnings": [],
   "recommendations": [
-    "Add and run a complete automated test suite (unit + integration) since test status is empty",
-    "expose actual library modules/functions in the MCP adapter instead of only setup.py helpers (`makeExtension`",
-    "`scandir`)",
-    "migrate packaging to `pyproject.toml` (PEP 517/518/621) and keep `setup.py` minimal for compatibility",
-    "pin and separate dependencies into runtime/dev/test requirements (or extras) with reproducible lock files",
-    "add CI workflows (GitHub Actions) for multi-version Python testing",
-    "linting",
-    "and build checks",
-    "improve project structure clarity by documenting package APIs in `gmatch4py/*/__init__.py` and adding module-level docstrings",
-    "strengthen README with quickstart examples",
-    "supported Python versions",
-    "algorithm coverage",
-    "and benchmark guidance",
-    "add type hints and static analysis (mypy/pyright) for public APIs",
-    "implement code quality tooling (ruff/flake8",
-    "black",
-    "isort",
-    "pre-commit) and enforce via CI",
-    "add performance benchmarks and regression tracking for graph matching workloads",
-    "create robust error handling and input validation for graph/kernel interfaces",
-    "add security and maintenance hygiene (dependency updates",
-    "vulnerability scanning",
-    "LICENSE verification)",
-    "expand release process with semantic versioning",
+    "Add a modern test suite with pytest and meaningful unit/integration coverage (current test status is empty)",
+    "add CI to run tests across multiple Python versions and dependency combinations",
+    "migrate packaging to `pyproject.toml` (PEP 517/518/621) while keeping `setup.py` compatibility if needed",
+    "pin and expand dependencies with dev/test extras and lock files for reproducibility",
+    "improve README with quickstart/API examples and explicit supported Python versions",
+    "add type hints plus mypy/ruff/black/pre-commit for code quality gates",
+    "document and expose real library entry points beyond setup helpers (`makeExtension`",
+    "`scandir`) so MCP endpoints map to core functionality",
+    "add error handling and validation around import-mode MCP adapter calls with clear user-facing messages",
+    "create MCP endpoint tests (happy path",
+    "invalid input",
+    "dependency missing) and wire them into CI",
+    "add benchmark scripts and performance regression checks for graph matching workloads",
+    "include security and maintenance hygiene (Dependabot/Renovate",
+    "license metadata",
     "changelog",
-    "and automated package publishing",
-    "add MCP plugin tests and contract tests for endpoint correctness and import fallback behavior",
-    "improve observability in MCP service with structured logging and clear startup/health diagnostics"
+    "semantic versioning)",
+    "improve project structure consistency (clear package boundaries for embedding/ged/helpers/kernels and remove empty placeholder modules)",
+    "add environment templates (`.env.example`",
+    "optional `environment.yml`) and contributor docs (`CONTRIBUTING.md`",
+    "development setup)",
+    "add release automation (build wheels/sdist",
+    "publish on tag",
+    "artifact verification)",
+    "and investigate/import-fallback robustness by reducing dynamic import assumptions and raising import feasibility above 0.63"
   ],
   "performance_metrics": {
     "memory_usage_mb": 0,
@@ -188,36 +187,36 @@
   },
   "execution_analysis": {
     "success_factors": [
-      "Workflow reached terminal status `success` and executed all expected nodes: download, analysis, env, generate, run, review, finalize.",
-      "Repository import succeeded via zip fallback, allowing analysis and plugin generation to proceed despite non-standard ingestion path.",
-      "Low intrusiveness risk and high import feasibility (0.86) enabled adapter generation in import mode.",
-      "Generated MCP service started healthy over stdio transport, indicating baseline runtime viability."
+      "Workflow completed end-to-end with status=success across all planned nodes (download, analysis, env, generate, run, review, finalize).",
+      "Low intrusiveness risk and import-mode adapter strategy enabled non-invasive MCP wrapping.",
+      "MCP plugin started healthy over stdio, indicating runnable generated service scaffold.",
+      "Repository was successfully ingested via zip fallback despite non-ideal analysis path."
     ],
     "failure_reasons": [
-      "No hard workflow failure occurred; however, functional outcome is partially limited because generated endpoints target setup helpers (`makeExtension`, `scandir`) rather than core graph-matching APIs.",
-      "Validation depth is weak: original project tests were not effectively executed (`passed: false`, empty details, 0 execution time), and MCP endpoint contract coverage is absent.",
-      "Analysis enrichment failed from DeepWiki (`success: false`), reducing semantic discovery quality for tool generation.",
-      "Observability/metrics fields are mostly zero or unknown (resource and performance telemetry incomplete), masking real bottlenecks."
+      "No hard workflow failure occurred.",
+      "DeepWiki analysis failed (external analysis subsystem), reducing semantic coverage for endpoint discovery.",
+      "Original project tests were effectively non-validated (passed=false, empty details, zero execution), limiting confidence in behavioral correctness.",
+      "Generated metadata appears inconsistent (tool_endpoints=0 vs discovered endpoints makeExtension/scandir), indicating reporting/generation quality gap."
     ],
-    "overall_assessment": "fair",
+    "overall_assessment": "good",
     "node_performance": {
-      "download_time": "Completed successfully; exact per-node timing not provided. Zip fallback import indicates resilient acquisition but likely added overhead and reduced metadata fidelity.",
-      "analysis_time": "Completed with medium complexity classification and dependency/risk extraction; however, semantic extraction was shallow (setup.py-focused), suggesting analysis quality bottleneck rather than runtime bottleneck.",
-      "generation_time": "Generation completed quickly enough within total 176.02s and produced 7 files; output appears scaffold-heavy with low business-function exposure.",
-      "test_time": "MCP health check passed, but effective test execution is near-zero for original project and plugin contracts; this is the primary validation gap."
+      "download_time": "Completed successfully; exact per-node timing unavailable. Repository is small (11 files), so download overhead is likely low.",
+      "analysis_time": "Completed with partial quality degradation (DeepWiki failure, no entry points detected initially). Static/AST-derived fallback still extracted setup.py functions.",
+      "generation_time": "Completed successfully; 7 MCP files generated with import adapter and runnable entrypoint.",
+      "test_time": "MCP health/run checks passed; original project test validation was effectively absent, so test phase quality is weak."
     },
     "resource_usage": {
-      "memory_efficiency": "Undetermined due to missing metrics (reported 0 MB). No evidence of memory pressure, but instrumentation is insufficient.",
-      "cpu_efficiency": "Undetermined due to missing metrics (reported 0%). Workflow duration is modest, suggesting no obvious CPU saturation.",
-      "disk_usage": "Low absolute footprint (small repo, few generated files), but generated file size/LOC telemetry shows zeros, indicating reporting defects."
+      "memory_efficiency": "Not measurable from provided metrics (reported as 0), but workload size suggests low memory footprint.",
+      "cpu_efficiency": "Not measurable from provided metrics (reported as 0); execution duration (170s) seems dominated by orchestration, not compute.",
+      "disk_usage": "Low absolute disk impact expected (small source tree, 7 generated files), but generated size metrics are missing/zeroed."
     }
   },
   "technical_quality": {
-    "code_quality_score": 62,
-    "architecture_score": 68,
-    "performance_score": 55,
-    "maintainability_score": 64,
+    "code_quality_score": 68,
+    "architecture_score": 72,
+    "performance_score": 60,
+    "maintainability_score": 65,
     "security_score": 85,
-    "scalability_score": 58
+    "scalability_score": 62
   }
 }

port.json

@@ -1,5 +1,5 @@
 {
   "repo": "GMatch4py",
-  "port": 7862,
-  "timestamp": 1773287346
+  "port": 7887,
+  "timestamp": 1773496505
 }

requirements.txt

@@ -7,4 +7,4 @@ scipy
 networkx==2.1
 numpy
 cython
-gmatch4py
+scikit-learn

run_docker.ps1

@@ -1,7 +1,7 @@
 cd $PSScriptRoot
 $ErrorActionPreference = "Stop"
 $entryName = if ($env:MCP_ENTRY_NAME) { $env:MCP_ENTRY_NAME } else { "GMatch4py" }
-$entryUrl  = if ($env:MCP_ENTRY_URL)  { $env:MCP_ENTRY_URL  } else { "http://localhost:7862/mcp" }
+$entryUrl  = if ($env:MCP_ENTRY_URL)  { $env:MCP_ENTRY_URL  } else { "http://localhost:7887/mcp" }
 $imageName = if ($env:MCP_IMAGE_NAME) { $env:MCP_IMAGE_NAME } else { "GMatch4py-mcp" }
 $mcpDir = Join-Path $env:USERPROFILE ".cursor"
 $mcpPath = Join-Path $mcpDir "mcp.json"
@@ -23,4 +23,4 @@ $serversOrdered[$entryName] = @{ url = $entryUrl }
 $config = @{ mcpServers = $serversOrdered }
 $config | ConvertTo-Json -Depth 10 | Set-Content -Path $mcpPath -Encoding UTF8
 docker build -t $imageName .
-docker run --rm -p 7862:7860 $imageName
+docker run --rm -p 7887:7860 $imageName

run_docker.sh

@@ -2,7 +2,7 @@
 set -euo pipefail
 cd "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
 mcp_entry_name="${MCP_ENTRY_NAME:-GMatch4py}"
-mcp_entry_url="${MCP_ENTRY_URL:-http://localhost:7862/mcp}"
+mcp_entry_url="${MCP_ENTRY_URL:-http://localhost:7887/mcp}"
 mcp_dir="${HOME}/.cursor"
 mcp_path="${mcp_dir}/mcp.json"
 mkdir -p "${mcp_dir}"
@@ -72,4 +72,4 @@ elif command -v jq >/dev/null 2>&1; then
   fi
 fi
 docker build -t GMatch4py-mcp .
-docker run --rm -p 7862:7860 GMatch4py-mcp
+docker run --rm -p 7887:7860 GMatch4py-mcp