flock-core 0.5.0b28__py3-none-any.whl → 0.5.0b51__py3-none-any.whl

flock/{core/logging → logging}/telemetry.py

@@ -7,19 +7,19 @@ from opentelemetry import trace
 from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import SimpleSpanProcessor
-from temporalio import workflow
 
-from flock.core.logging.span_middleware.baggage_span_processor import (
+# from temporalio import workflow
+from flock.logging.span_middleware.baggage_span_processor import (
     BaggageAttributeSpanProcessor,
 )
 
-with workflow.unsafe.imports_passed_through():
-    from flock.core.logging.telemetry_exporter.file_exporter import (
-        FileSpanExporter,
-    )
-    from flock.core.logging.telemetry_exporter.sqlite_exporter import (
-        SqliteTelemetryExporter,
-    )
+# with workflow.unsafe.imports_passed_through():
+from flock.logging.telemetry_exporter.file_exporter import (
+    FileSpanExporter,
+)
+from flock.logging.telemetry_exporter.sqlite_exporter import (
+    SqliteTelemetryExporter,
+)
 
 
 class TelemetryConfig:
@@ -73,7 +73,12 @@ class TelemetryConfig:
 
     def _should_setup(self) -> bool:
         # Respect explicit disable flag for tests and minimal setups
-        if os.environ.get("FLOCK_DISABLE_TELEMETRY_AUTOSETUP", "").lower() in {"1", "true", "yes", "on"}:
+        if os.environ.get("FLOCK_DISABLE_TELEMETRY_AUTOSETUP", "").lower() in {
+            "1",
+            "true",
+            "yes",
+            "on",
+        }:
             return False
         try:
             # If a provider is already installed (typically by user/tests), don't override it
@@ -122,13 +127,10 @@ class TelemetryConfig:
                     collector_endpoint=self.jaeger_endpoint,
                 )
             else:
-                raise ValueError(
-                    "Invalid JAEGER_TRANSPORT specified. Use 'grpc' or 'http'."
-                )
+                raise ValueError("Invalid JAEGER_TRANSPORT specified. Use 'grpc' or 'http'.")
 
             span_processors.append(SimpleSpanProcessor(jaeger_exporter))
 
-
         if self.enable_otlp:
             if self.otlp_protocol == "grpc":
                 from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
@@ -156,16 +158,12 @@ class TelemetryConfig:
 
         # If a file path is provided, add the custom file exporter.
         if self.file_export_name and self.enable_file:
-            file_exporter = FileSpanExporter(
-                self.local_logging_dir, self.file_export_name
-            )
+            file_exporter = FileSpanExporter(self.local_logging_dir, self.file_export_name)
             span_processors.append(SimpleSpanProcessor(file_exporter))
 
         # If a SQLite database path is provided, ensure the DB exists and add the SQLite exporter.
         if self.sqlite_db_name and self.enable_sql:
-            sqlite_exporter = SqliteTelemetryExporter(
-                self.local_logging_dir, self.sqlite_db_name
-            )
+            sqlite_exporter = SqliteTelemetryExporter(self.local_logging_dir, self.sqlite_db_name)
             span_processors.append(SimpleSpanProcessor(sqlite_exporter))
 
         # Register all span processors with the provider.
@@ -190,10 +188,6 @@ class TelemetryConfig:
             return
 
         # Use OpenTelemetry to record the exception
-        with self.global_tracer.start_as_current_span(
-            "UnhandledException"
-        ) as span:
+        with self.global_tracer.start_as_current_span("UnhandledException") as span:
             span.record_exception(exc_value)
-            span.set_status(
-                trace.Status(trace.StatusCode.ERROR, str(exc_value))
-            )
+            span.set_status(trace.Status(trace.StatusCode.ERROR, str(exc_value)))

flock/{core/logging → logging}/telemetry_exporter/base_exporter.py

@@ -25,14 +25,14 @@ class TelemetryExporter(SpanExporter, ABC):
             self.shutdown()
 
     @abstractmethod
-    def export(self, spans) -> SpanExportResult | None:
+    def export(self, spans) -> SpanExportResult:  # type: ignore[override]
         """Export spans to the configured backend.
 
         To be implemented by subclasses.
+        May return SUCCESS, FAILURE, or None (handled by _export wrapper).
         """
         raise NotImplementedError("Subclasses must implement the export method")
 
     @abstractmethod
     def shutdown(self):
         """Cleanup resources, if any. Optional for subclasses."""
-        pass

flock/{core/logging → logging}/telemetry_exporter/file_exporter.py

@@ -2,17 +2,17 @@
 
 import json
 
+# with workflow.unsafe.imports_passed_through():
+from pathlib import Path
+
 from opentelemetry.sdk.trace.export import SpanExportResult
 from opentelemetry.trace import Status, StatusCode
-from temporalio import workflow
 
-from flock.core.logging.telemetry_exporter.base_exporter import (
+# from temporalio import workflow
+from flock.logging.telemetry_exporter.base_exporter import (
     TelemetryExporter,
 )
 
-with workflow.unsafe.imports_passed_through():
-    from pathlib import Path
-
 
 class FileSpanExporter(TelemetryExporter):
     """A simple exporter that writes span data as JSON lines into a file."""
@@ -63,10 +63,7 @@ class FileSpanExporter(TelemetryExporter):
                 }
                 for link in span.links
             ],
-            "resource": {
-                attr_key: attr_value
-                for attr_key, attr_value in span.resource.attributes.items()
-            },
+            "resource": dict(span.resource.attributes.items()),
         }
 
     def export(self, spans):

flock/{core/logging → logging}/telemetry_exporter/sqlite_exporter.py

@@ -7,7 +7,7 @@ from typing import Any
 
 from opentelemetry.sdk.trace.export import SpanExportResult
 
-from flock.core.logging.telemetry_exporter.base_exporter import (
+from flock.logging.telemetry_exporter.base_exporter import (
     TelemetryExporter,
 )
 
@@ -77,7 +77,7 @@ class SqliteTelemetryExporter(TelemetryExporter):
                 trace_id = format(span.context.trace_id, "032x")
                 cursor.execute(
                     """
-                    INSERT OR REPLACE INTO spans 
+                    INSERT OR REPLACE INTO spans
                     (id, name, trace_id, span_id, start_time, end_time, attributes, status)
                     VALUES (?, ?, ?, ?, ?, ?, ?, ?)
                     """,
@@ -100,4 +100,3 @@ class SqliteTelemetryExporter(TelemetryExporter):
 
     def shutdown(self) -> None:
         """Cleanup resources."""
-        pass

flock/{core/logging → logging}/trace_and_logged.py

@@ -5,7 +5,8 @@ import inspect
 
 from opentelemetry import trace
 
-from flock.core.logging.logging import get_logger
+from flock.logging.logging import get_logger
+
 
 logger = get_logger("tools")
 tracer = trace.get_tracer(__name__)
@@ -27,33 +28,28 @@ def traced_and_logged(func):
                 try:
                     result = await func(*args, **kwargs)
                     span.set_attribute("result", str(result))
-                    logger.debug(
-                        f"{func.__name__} executed successfully", result=result
-                    )
+                    logger.debug(f"{func.__name__} executed successfully", result=result)
                     return result
                 except Exception as e:
-                    logger.error(f"Error in {func.__name__}", error=str(e))
+                    logger.exception(f"Error in {func.__name__}", error=str(e))
                     span.record_exception(e)
                     raise
 
         return async_wrapper
-    else:
-
-        @functools.wraps(func)
-        def wrapper(*args, **kwargs):
-            with tracer.start_as_current_span(func.__name__) as span:
-                span.set_attribute("args", str(args))
-                span.set_attribute("kwargs", str(kwargs))
-                try:
-                    result = func(*args, **kwargs)
-                    span.set_attribute("result", str(result))
-                    logger.debug(
-                        f"{func.__name__} executed successfully", result=result
-                    )
-                    return result
-                except Exception as e:
-                    logger.error(f"Error in {func.__name__}", error=str(e))
-                    span.record_exception(e)
-                    raise
 
-        return wrapper
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        with tracer.start_as_current_span(func.__name__) as span:
+            span.set_attribute("args", str(args))
+            span.set_attribute("kwargs", str(kwargs))
+            try:
+                result = func(*args, **kwargs)
+                span.set_attribute("result", str(result))
+                logger.debug(f"{func.__name__} executed successfully", result=result)
+                return result
+            except Exception as e:
+                logger.exception(f"Error in {func.__name__}", error=str(e))
+                span.record_exception(e)
+                raise
+
+    return wrapper

flock/mcp/__init__.py

@@ -0,0 +1,91 @@
+"""MCP (Model Context Protocol) Integration for Flock-Flow.
+
+This package provides integration with MCP servers, enabling agents to
+dynamically discover and use external tools following the Model Context Protocol.
+
+Architecture Decisions:
+- AD001: Two-Level Architecture (orchestrator + agent)
+- AD003: Tool Namespacing ({server}__{tool})
+- AD004: Per-(agent_id, run_id) Connection Isolation
+- AD005: Lazy Connection Establishment
+- AD007: Graceful Degradation on MCP Failures
+
+Key Components:
+- FlockMCPConfiguration: Server configuration
+- FlockMCPClient: Individual server connection
+- FlockMCPClientManager: Connection pooling and lifecycle
+- FlockMCPTool: MCP tool wrapper compatible with DSPy
+
+Example Usage:
+    ```python
+    from flock import Flock
+    from flock.mcp import StdioServerParameters
+
+    # Create orchestrator
+    orchestrator = Flock()
+
+    # Register MCP server
+    orchestrator.add_mcp(
+        name="filesystem",
+        connection_params=StdioServerParameters(
+            command="uvx",
+            args=["mcp-server-filesystem", "/tmp"]
+        )
+    )
+
+    # Build agent with MCP access
+    agent = (
+        orchestrator.agent("file_agent")
+        .with_mcps(["filesystem"])
+        .build()
+    )
+    ```
+"""
+
+from flock.mcp.client import FlockMCPClient
+from flock.mcp.config import (
+    FlockMCPCachingConfiguration,
+    FlockMCPCallbackConfiguration,
+    FlockMCPConfiguration,
+    FlockMCPConnectionConfiguration,
+    FlockMCPFeatureConfiguration,
+)
+from flock.mcp.manager import FlockMCPClientManager
+from flock.mcp.tool import FlockMCPTool
+from flock.mcp.types import (
+    FlockListRootsMCPCallback,
+    FlockLoggingMCPCallback,
+    FlockMessageHandlerMCPCallback,
+    FlockSamplingMCPCallback,
+    MCPRoot,
+    ServerParameters,
+    SseServerParameters,
+    StdioServerParameters,
+    StreamableHttpServerParameters,
+    WebsocketServerParameters,
+)
+
+
+__all__ = [
+    "FlockListRootsMCPCallback",
+    "FlockLoggingMCPCallback",
+    "FlockMCPCachingConfiguration",
+    "FlockMCPCallbackConfiguration",
+    # Client and Manager
+    "FlockMCPClient",
+    "FlockMCPClientManager",
+    # Configuration
+    "FlockMCPConfiguration",
+    "FlockMCPConnectionConfiguration",
+    "FlockMCPFeatureConfiguration",
+    "FlockMCPTool",
+    "FlockMessageHandlerMCPCallback",
+    "FlockSamplingMCPCallback",
+    "MCPRoot",
+    # Types
+    "ServerParameters",
+    "SseServerParameters",
+    "StdioServerParameters",
+    "StreamableHttpServerParameters",
+    "WebsocketServerParameters",
+]