PyStreamMCP 3.3.0__py3-none-any.whl → 3.3.2__py3-none-any.whl

pystreammcp/__init__.py

@@ -7,7 +7,7 @@ Reduces token usage by 60-75% while maintaining quality.
 Includes StatGuardian integration for data quality validation.
 """
 
-__version__ = "3.3.0"
+__version__ = "3.3.2"
 
 from .agent import Agent, QueryResult
 from .query import Query, QueryIntent, QueryConstraints

pystreammcp/cli.py

@@ -2,11 +2,9 @@
 
 import json
 import sys
-from typing import Optional
 import click
 
 from pystreammcp import Agent, __version__
-from pystreammcp.api import PyStreamMCPAPI
 from pystreammcp.cli_dashboard import PyStreamMCPDashboard
 
 
@@ -83,6 +81,16 @@ def query(
 @click.option("--reload", is_flag=True)
 def server(host: str, port: int, reload: bool):
     """Start PyStreamMCP API server."""
+    try:
+        from pystreammcp.api import PyStreamMCPAPI
+    except ImportError:
+        click.echo(
+            "Error: the 'server' command requires the 'api' extra. "
+            "Install with: pip install 'pystreammcp[api]'",
+            err=True,
+        )
+        raise SystemExit(1)
+
     click.echo(f"Starting server on {host}:{port}...")
     api = PyStreamMCPAPI()
     api.run(host=host, port=port, reload=reload)
@@ -124,162 +132,5 @@ def dashboard(
         sys.exit(1)
 
 
-# Legacy CLI interface for compatibility
-class CLIInterface:
-    """Command-line interface for PyStreamMCP (legacy)."""
-
-    def __init__(self):
-        self.agent = None
-
-    def create_agent(
-        self, agent_id: str, strategy: str = "balanced", max_tokens: int = 2000
-    ):
-        """Create an agent."""
-        self.agent = Agent(
-            agent_id=agent_id,
-            optimization_strategy=strategy,
-            max_tokens=max_tokens,
-        )
-        return {"status": "success", "agent_id": agent_id}
-
-    def query(
-        self, text: str, intent: str = "retrieve", agent_id: Optional[str] = None
-    ) -> dict:
-        """Execute a query."""
-        if agent_id:
-            self.create_agent(agent_id)
-
-        if not self.agent:
-            return {"status": "error", "message": "No agent created"}
-
-        result = self.agent.query(text)
-
-        return {
-            "status": "success",
-            "query_id": result.query_id,
-            "query_text": text,
-            "baseline_tokens": result.baseline_tokens,
-            "optimized_tokens": result.optimized_tokens,
-            "cost_reduction_percent": result.cost_reduction_percent,
-            "cost_saved": (result.baseline_tokens - result.optimized_tokens) * 0.00001,
-            "execution_time_ms": result.execution_time_ms,
-            "meets_target": 60 <= result.cost_reduction_percent <= 75,
-        }
-
-    def get_metrics(self) -> dict:
-        """Get agent metrics."""
-        if not self.agent:
-            return {"status": "error", "message": "No agent created"}
-
-        metrics = self.agent.get_metrics()
-        return {
-            "status": "success",
-            "metrics": metrics,
-        }
-
-
-def main():
-    """Main CLI entry point."""
-    cli = CLIInterface()
-
-    if len(sys.argv) < 2:
-        print_help()
-        sys.exit(1)
-
-    command = sys.argv[1]
-
-    try:
-        if command == "query":
-            if len(sys.argv) < 3:
-                print(json.dumps({"error": "Missing query text"}))
-                sys.exit(1)
-
-            text = sys.argv[2]
-            intent = sys.argv[3] if len(sys.argv) > 3 else "retrieve"
-            agent_id = sys.argv[4] if len(sys.argv) > 4 else "cli_agent"
-
-            result = cli.query(text, intent=intent, agent_id=agent_id)
-            print(json.dumps(result))
-
-        elif command == "create-agent":
-            if len(sys.argv) < 3:
-                print(json.dumps({"error": "Missing agent_id"}))
-                sys.exit(1)
-
-            agent_id = sys.argv[2]
-            strategy = sys.argv[3] if len(sys.argv) > 3 else "balanced"
-            max_tokens = int(sys.argv[4]) if len(sys.argv) > 4 else 2000
-
-            result = cli.create_agent(agent_id, strategy, max_tokens)
-            print(json.dumps(result))
-
-        elif command == "metrics":
-            result = cli.get_metrics()
-            print(json.dumps(result))
-
-        elif command == "help":
-            print_help()
-
-        else:
-            print(json.dumps({"error": f"Unknown command: {command}"}))
-            sys.exit(1)
-
-    except Exception as e:
-        print(json.dumps({"error": str(e), "status": "error"}))
-        sys.exit(1)
-
-
-def print_help():
-    """Print help message."""
-    help_text = """
-PyStreamMCP CLI - Intelligence Layer for Workflows
-
-USAGE:
-    pystreammcp <command> [options]
-
-COMMANDS:
-    query <text> [intent] [agent_id]
-        Execute a query with optimization
-        - text: The query text (required)
-        - intent: Query type (retrieve|discover|aggregate) (default: retrieve)
-        - agent_id: Agent identifier (default: cli_agent)
-
-        Example:
-            pystreammcp query "Top 10 customers by LTV" retrieve my_agent
-
-    create-agent <agent_id> [strategy] [max_tokens]
-        Create an agent with specific configuration
-        - agent_id: Agent identifier (required)
-        - strategy: Optimization strategy (balanced|token_efficient|quality_first) (default: balanced)
-        - max_tokens: Token budget (default: 2000)
-
-        Example:
-            pystreammcp create-agent workflow_agent token_efficient 1500
-
-    metrics
-        Get current agent metrics
-
-        Example:
-            pystreammcp metrics
-
-    help
-        Show this help message
-
-OUTPUT FORMAT:
-    All commands return JSON output for easy parsing in workflows
-
-EXAMPLES:
-    # Query with cost tracking
-    pystreammcp query "Find churn risk customers"
-
-    # Efficient query for token-constrained environments
-    pystreammcp query "List segments" discover automation_agent
-
-    # Get metrics for reporting
-    pystreammcp metrics | jq '.metrics.total_cost_saved'
-"""
-    print(help_text)
-
-
 if __name__ == "__main__":
-    main()
+    cli()

pystreammcp/cli_daemon.py

@@ -1,16 +1,28 @@
 """Dashboard daemon - runs in background, restarts on close"""
 
+import re
+import shlex
 import subprocess
 import time
 import signal
 import sys
 from pathlib import Path
 
+_PACKAGE_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]*$")
+
 
 class DashboardDaemon:
     def __init__(self, package_name: str, dashboard_cmd: str):
+        if not isinstance(package_name, str) or not _PACKAGE_NAME_RE.match(
+            package_name
+        ):
+            raise ValueError(f"Invalid package name: {package_name!r}")
         self.package_name = package_name
-        self.dashboard_cmd = dashboard_cmd
+        # Split into argv and run without a shell so that a caller-supplied
+        # command cannot inject shell metacharacters.
+        self.dashboard_cmd = shlex.split(dashboard_cmd)
+        if not self.dashboard_cmd:
+            raise ValueError("dashboard_cmd must not be empty")
         self.process = None
         self.running = True
 
@@ -27,7 +39,7 @@ class DashboardDaemon:
 
                 self.process = subprocess.Popen(
                     self.dashboard_cmd,
-                    shell=True,
+                    shell=False,
                     stdout=subprocess.PIPE,
                     stderr=subprocess.PIPE,
                 )

pystreammcp/integrations/langchain.py

@@ -8,7 +8,7 @@ Provides both:
 2. Legacy PyStreamMCPTool & PyStreamMCPRetriever (backward compatible)
 """
 
-from typing import Optional, Dict, Any, List, Type
+from typing import Optional, Dict, Any, List, Type, TYPE_CHECKING
 import asyncio
 from pystreammcp import (
     Agent,
@@ -23,6 +23,10 @@ from pystreammcp import (
 from pystreammcp.adapters import QueryResult as AdapterQueryResult
 from pystreammcp.discovery import SourceRegistry
 
+if TYPE_CHECKING:
+    from langchain_core.tools import Tool as LangchainTool
+    from langchain_core.retrievers import BaseRetriever
+
 
 class LangchainAdapter(AgentFrameworkAdapter):
     """Langchain adapter using new AgentFrameworkAdapter base class.

pystreammcp/integrations/llamaindex.py

@@ -8,7 +8,7 @@ Provides both:
 2. Legacy StreamMCPRetriever (backward compatible)
 """
 
-from typing import Any, List, Optional, Dict
+from typing import Any, List, Optional, Dict, TYPE_CHECKING
 import asyncio
 from pystreammcp import (
     Agent,
@@ -22,6 +22,9 @@ from pystreammcp import (
 
 from pystreammcp.adapters import QueryResult as AdapterQueryResult
 
+if TYPE_CHECKING:
+    from llama_index.core.retrievers import BaseRetriever
+
 
 class LlamaIndexAdapter(AgentFrameworkAdapter):
     """LlamaIndex adapter using new AgentFrameworkAdapter base class.

pystreammcp/integrations/semantic_kernel.py

@@ -8,7 +8,7 @@ Provides both:
 2. Legacy PyStreamMCPPlugin (backward compatible)
 """
 
-from typing import Optional, Dict, Any
+from typing import Optional, Dict, Any, TYPE_CHECKING
 import asyncio
 from pystreammcp import (
     Agent,
@@ -22,6 +22,9 @@ from pystreammcp import (
 
 from pystreammcp.adapters import QueryResult as AdapterQueryResult
 
+if TYPE_CHECKING:
+    from semantic_kernel.functions import KernelPlugin
+
 
 class SemanticKernelAdapter(AgentFrameworkAdapter):
     """Semantic Kernel adapter using new AdapterFrameworkAdapter base class.

pystreammcp/multi_agent.py

@@ -1,5 +1,6 @@
 """Multi-agent context sharing and collaboration for PyStreamMCP."""
 
+from datetime import datetime, timezone
 from typing import Dict, List, Optional
 from dataclasses import dataclass
 from .context import Context
@@ -46,7 +47,7 @@ class ContextHub:
             optimized_context=context,
             usage_count=1,
             agents_using=[],
-            created_at=__import__("datetime").datetime.utcnow().isoformat(),
+            created_at=datetime.now(timezone.utc).isoformat(),
             cost_savings=cost_savings,
         )
         self.shared_contexts[context_id] = shared

pystreammcp/orchestration/airflow.py

@@ -8,6 +8,7 @@ from typing import Dict, Any, Optional
 from dataclasses import dataclass
 
 from pystreammcp import Agent
+from pystreammcp.discovery import SourceRegistry
 
 
 @dataclass
@@ -110,30 +111,38 @@ class PyStreamMCPDiscoveryOperator:
         agent_id: str,
         context_text: str,
         max_sources: int = 10,
+        registry: Optional[SourceRegistry] = None,
         **kwargs,
     ):
-        """Initialize discovery operator."""
+        """Initialize discovery operator.
+
+        Args:
+            registry: Optional shared SourceRegistry sources were
+                registered on elsewhere (e.g. via the FastAPI `/sources`
+                endpoint or another operator sharing the same registry).
+                Defaults to a fresh, empty registry.
+        """
         self.task_id = task_id
         self.agent_id = agent_id
         self.context_text = context_text
         self.max_sources = max_sources
+        self.registry = registry if registry is not None else SourceRegistry()
         self.kwargs = kwargs
 
     def execute(self, context: Dict[str, Any]) -> Dict[str, Any]:
-        """Execute discovery."""
+        """Execute discovery using the real SourceRegistry.
+
+        Uses the same relevance ranking as the REST/MCP/LangChain
+        surfaces instead of fabricating `source_0..source_4` results. An
+        operator given no registry (or one with nothing registered)
+        honestly returns zero sources rather than padding in fake ones.
+        """
+        sources = self.registry.discover(self.context_text, limit=self.max_sources)
         return {
             "task_id": self.task_id,
             "context": self.context_text,
-            "sources": [
-                {
-                    "name": f"source_{i}",
-                    "relevance": 0.95 - (i * 0.05),
-                    "type": "database",
-                    "estimated_tokens": 500 + (i * 100),
-                }
-                for i in range(min(self.max_sources, 5))
-            ],
-            "total_sources": min(self.max_sources, 5),
+            "sources": sources,
+            "total_sources": len(sources),
             "timestamp": str(context.get("execution_date", "")),
         }
 

pystreammcp/orchestration/nocode_rpa.py

@@ -8,6 +8,7 @@ from typing import Dict, Any, Optional
 import json
 
 from pystreammcp import Agent
+from pystreammcp.discovery import SourceRegistry
 
 
 class N8nWebhookTrigger:
@@ -22,13 +23,17 @@ class N8nWebhookTrigger:
     3. Add query in body: {"text": "your query", "agent_id": "agent_1"}
     """
 
-    def __init__(self, agent_id: str = "n8n_agent"):
+    def __init__(self, agent_id: str = "n8n_agent", registry: Optional[SourceRegistry] = None):
         """Initialize webhook trigger.
 
         Args:
             agent_id: PyStreamMCP agent ID
+            registry: Optional shared SourceRegistry sources were
+                registered on elsewhere (e.g. via the FastAPI `/sources`
+                endpoint). Defaults to a fresh, empty registry.
         """
         self.agent_id = agent_id
+        self.registry = registry if registry is not None else SourceRegistry()
 
     def handle_query(self, body: Dict[str, Any]) -> Dict[str, Any]:
         """Handle incoming webhook request.
@@ -61,23 +66,22 @@ class N8nWebhookTrigger:
         }
 
     def handle_discovery(self, body: Dict[str, Any]) -> Dict[str, Any]:
-        """Handle discovery webhook."""
+        """Handle discovery webhook.
+
+        Uses the real `SourceRegistry.discover()` instead of fabricating
+        `source_0..source_4` results. With nothing registered on this
+        trigger's registry, honestly returns zero sources.
+        """
         context = body.get("context", "")
 
         if not context:
             return {"error": "Missing 'context' parameter"}
 
+        sources = self.registry.discover(context)
         return {
             "context": context,
-            "sources": [
-                {
-                    "name": f"source_{i}",
-                    "relevance": 0.95 - (i * 0.05),
-                    "type": "data_source",
-                }
-                for i in range(5)
-            ],
-            "total_sources": 5,
+            "sources": sources,
+            "total_sources": len(sources),
             "success": True,
         }
 

pystreammcp/orchestration/temporal.py

@@ -8,6 +8,7 @@ from typing import Dict, Any, Optional
 from dataclasses import dataclass
 
 from pystreammcp import Agent
+from pystreammcp.discovery import SourceRegistry
 
 
 @dataclass
@@ -55,23 +56,26 @@ class TemporalDiscoveryActivity:
     agent_id: str
     context: str
     max_sources: int = 10
+    registry: Optional[SourceRegistry] = None
 
     def execute(self) -> Dict[str, Any]:
-        """Execute discovery as a durable activity."""
-        agent = Agent(agent_id=self.agent_id)
+        """Execute discovery as a durable activity.
+
+        Uses the real `SourceRegistry.discover()` -- the same relevance
+        ranking used by the REST/MCP/LangChain surfaces -- instead of
+        fabricating `source_0..source_4` results. Pass `registry=` a
+        shared `SourceRegistry` instance (the one sources were registered
+        on elsewhere) so this activity can actually find them; an
+        activity given no registry gets a fresh, empty one and will
+        honestly report zero sources rather than padding in fake ones.
+        """
+        registry = self.registry if self.registry is not None else SourceRegistry()
+        sources = registry.discover(self.context, limit=self.max_sources)
 
-        # In production, use actual discovery logic
         return {
             "context": self.context,
-            "sources": [
-                {
-                    "name": f"source_{i}",
-                    "relevance": 0.95 - (i * 0.05),
-                    "type": "database",
-                }
-                for i in range(min(self.max_sources, 5))
-            ],
-            "total_sources": min(self.max_sources, 5),
+            "sources": sources,
+            "total_sources": len(sources),
             "status": "completed",
         }
 
@@ -87,15 +91,21 @@ class TemporalWorkflow:
     5. Handle failures with retries
     """
 
-    def __init__(self, workflow_id: str, agent_id: str):
+    def __init__(
+        self, workflow_id: str, agent_id: str, registry: Optional[SourceRegistry] = None
+    ):
         """Initialize workflow.
 
         Args:
             workflow_id: Unique workflow identifier
             agent_id: PyStreamMCP agent ID
+            registry: Optional shared SourceRegistry sources were
+                registered on elsewhere (e.g. via the FastAPI `/sources`
+                endpoint). Defaults to a fresh, empty registry.
         """
         self.workflow_id = workflow_id
         self.agent_id = agent_id
+        self.registry = registry if registry is not None else SourceRegistry()
 
     def discover_sources(self, context: str) -> Dict[str, Any]:
         """Activity: Discover relevant sources.
@@ -104,11 +114,11 @@ class TemporalWorkflow:
         ```python
         sources = await workflow.execute_activity(
             TemporalDiscoveryActivity,
-            TemporalDiscoveryActivity(self.agent_id, context),
+            TemporalDiscoveryActivity(self.agent_id, context, registry=self.registry),
         )
         ```
         """
-        activity = TemporalDiscoveryActivity(self.agent_id, context)
+        activity = TemporalDiscoveryActivity(self.agent_id, context, registry=self.registry)
         return activity.execute()
 
     def optimize_query(self, query_text: str) -> Dict[str, Any]:

pystreammcp/quality.py

@@ -6,7 +6,7 @@ Ensures all context included in queries has passed data quality checks.
 
 from typing import Optional, List, Dict, Any
 from dataclasses import dataclass, field
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from enum import Enum
 import logging
 
@@ -31,7 +31,7 @@ class QualityCheck:
     passed: bool
     score: float  # 0.0-1.0
     message: str = ""
-    checked_at: datetime = field(default_factory=datetime.utcnow)
+    checked_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
 
     def __post_init__(self):
         self.score = max(0.0, min(1.0, self.score))
@@ -46,7 +46,7 @@ class ValidationResult:
     quality_score: float  # 0.0-1.0
     checks: List[QualityCheck] = field(default_factory=list)
     errors: List[str] = field(default_factory=list)
-    last_validated: datetime = field(default_factory=datetime.utcnow)
+    last_validated: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
     validation_id: str = ""
 
     def __post_init__(self):
@@ -66,7 +66,7 @@ class ValidationResult:
             return True
 
         if self.status == QualityStatus.STALE and max_staleness_seconds:
-            age = (datetime.utcnow() - self.last_validated).total_seconds()
+            age = (datetime.now(timezone.utc) - self.last_validated).total_seconds()
             return age <= max_staleness_seconds
 
         if self.status == QualityStatus.DEGRADED:
@@ -148,7 +148,7 @@ class QualityValidator:
         # Check cache first
         cached = self._validation_cache.get(dataset_id)
         if cached:
-            age = (datetime.utcnow() - cached.last_validated).total_seconds()
+            age = (datetime.now(timezone.utc) - cached.last_validated).total_seconds()
             if age < gate.max_staleness_seconds:
                 logger.debug(f"Using cached validation for {dataset_id}")
                 return cached
@@ -379,7 +379,7 @@ class QualityValidator:
                     "status": result.status,
                     "quality_score": result.quality_score,
                     "age_seconds": (
-                        datetime.utcnow() - result.last_validated
+                        datetime.now(timezone.utc) - result.last_validated
                     ).total_seconds(),
                 }
                 for dataset_id, result in self._validation_cache.items()

pystreammcp/server.py

@@ -5,7 +5,7 @@ import hashlib
 import hmac
 import os
 from typing import Dict, Any, Optional, List, Tuple
-from datetime import datetime
+from datetime import datetime, timezone
 from pystreammcp import Agent
 from .webhook_router import EventRouter, MCPEndpoint, Tool
 from .webhook_handlers import OrchestrationWebhookHandlers
@@ -194,7 +194,7 @@ class PyStreamMCPServer:
             "secret_key": secret_key,
             "headers": headers or {},
             "active": True,
-            "created_at": datetime.utcnow().isoformat(),
+            "created_at": datetime.now(timezone.utc).isoformat(),
         }
         return {
             "status": "success",
@@ -342,7 +342,7 @@ class PyStreamMCPServer:
             "status": "success",
             "orchestration": status,
             "webhooks": len(self.webhook_configs),
-            "timestamp": datetime.utcnow().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
         }