flock-core 0.5.0b28__py3-none-any.whl → 0.5.56b0__py3-none-any.whl

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

@@ -14,13 +14,12 @@ import logging
 import sys
 from typing import Literal
 
-from opentelemetry import trace
-
 # Always import Temporal workflow (since it's part of the project)
-from temporalio import workflow
+# from temporalio import workflow
+# with workflow.unsafe.imports_passed_through():
+from loguru import logger as loguru_logger
+from opentelemetry import trace
 
-with workflow.unsafe.imports_passed_through():
-    from loguru import logger as loguru_logger
 
 # ENABLED_FLOCK_LOGGER_LEVELS constant removed
 
@@ -42,13 +41,14 @@ def in_workflow_context() -> bool:
     It does this by attempting to call workflow.info() and returning True
     if successful. Otherwise, it returns False.
     """
-    try:
-        workflow.logger.debug("Checking if in workflow context...")
-        # loguru_logger.debug("Checking if in workflow context...")
-        # This call will succeed only if we're in a workflow context.
-        return bool(hasattr(workflow.info(), "is_replaying"))
-    except Exception:
-        return False
+    return False
+    # try:
+    #     workflow.logger.debug("Checking if in workflow context...")
+    #     # loguru_logger.debug("Checking if in workflow context...")
+    #     # This call will succeed only if we're in a workflow context.
+    #     return bool(hasattr(workflow.info(), "is_replaying"))
+    # except Exception:
+    #     return False
 
 
 def get_current_trace_id() -> str:
@@ -108,7 +108,7 @@ COLOR_MAP = {
 
 LOGGERS = [
     "flock",  # Core Flock orchestration
-    "flock.api", # Flock API specific logs
+    "flock.api",  # Flock API specific logs
     "agent",  # General agent operations
     "context",  # Context management
     "registry",  # Unified registry operations (new)
@@ -177,9 +177,7 @@ def custom_format(record):
     # MAX_LENGTH = 500 # Example value
     if len(message) > MAX_LENGTH:
         truncated_chars = len(message) - MAX_LENGTH
-        message = (
-            message[:MAX_LENGTH] + f"<yellow>...+({truncated_chars} chars)</yellow>"
-        )
+        message = message[:MAX_LENGTH] + f"<yellow>...+({truncated_chars} chars)</yellow>"
 
     # Determine if category needs bolding (can refine this logic)
     needs_bold = category in BOLD_CATEGORIES
@@ -247,7 +245,6 @@ class PrintAndFlushSink:
 
         Already flushed on every write call.
         """
-        pass
 
 
 # Configure Loguru for non-workflow (local/worker) contexts.
@@ -264,7 +261,9 @@ logging.basicConfig(level=LOG_LEVELS["ERROR"])  # Default to ERROR level for fal
 # loguru_logger.add("logs/flock.log", rotation="100 MB", retention="30 days", level="DEBUG")
 
 
-def get_default_severity(level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL", "NO_LOGS", "SUCCESS"] | int) -> int:
+def get_default_severity(
+    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL", "NO_LOGS", "SUCCESS"] | int,
+) -> int:
     """Get the default severity for a given level."""
     if isinstance(level, str):
         level_str = level.upper()
@@ -272,9 +271,17 @@ def get_default_severity(level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CR
     return level
 
 
-def configure_logging(flock_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL", "NO_LOGS", "SUCCESS"] | int,
-                      external_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL", "NO_LOGS", "SUCCESS"] | int,
-                      specific_levels: dict[str, Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL", "NO_LOGS", "SUCCESS"] | int] | None = None) -> None:
+def configure_logging(
+    flock_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL", "NO_LOGS", "SUCCESS"]
+    | int,
+    external_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL", "NO_LOGS", "SUCCESS"]
+    | int,
+    specific_levels: dict[
+        str,
+        Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL", "NO_LOGS", "SUCCESS"] | int,
+    ]
+    | None = None,
+) -> None:
     """Configure both external and internal Flock logging systems.
 
     Args:
@@ -283,19 +290,21 @@ def configure_logging(flock_level: Literal["DEBUG", "INFO", "WARNING", "ERROR",
         specific_levels (dict[str, str | int] | None, optional): A dictionary mapping
             logger names to their specific logging levels. Defaults to None.
     """
-    # Get default severity
+    global _DEFAULT_FLOCK_SEVERITY, _SPECIFIC_SEVERITIES
 
+    # Get default severity
     external_severity = get_default_severity(external_level)
     logging.basicConfig(level=external_severity)
 
-
     flock_severity = get_default_severity(flock_level)
+    _DEFAULT_FLOCK_SEVERITY = flock_severity  # Store for future loggers
 
     specific_severities = {}
     if specific_levels:
         for name, logger_level in specific_levels.items():
             severity = get_default_severity(logger_level)
             specific_severities[name] = severity
+            _SPECIFIC_SEVERITIES[name] = severity  # Store for future loggers
 
     # Apply to all cached loggers
     for logger_name, log_instance in _LOGGER_CACHE.items():
@@ -306,28 +315,26 @@ def configure_logging(flock_level: Literal["DEBUG", "INFO", "WARNING", "ERROR",
         log_instance.min_level_severity = target_severity
 
 
-
-
 # Define a dummy logger that does nothing
 class DummyLogger:
     """A dummy logger that does nothing when called."""
 
-    def debug(self, *args, **kwargs):  # noqa: D102
+    def debug(self, *args, **kwargs):
         pass
 
-    def info(self, *args, **kwargs):  # noqa: D102
+    def info(self, *args, **kwargs):
         pass
 
-    def warning(self, *args, **kwargs):  # noqa: D102
+    def warning(self, *args, **kwargs):
         pass
 
-    def error(self, *args, **kwargs):  # noqa: D102
+    def error(self, *args, **kwargs):
         pass
 
-    def exception(self, *args, **kwargs):  # noqa: D102
+    def exception(self, *args, **kwargs):
         pass
 
-    def success(self, *args, **kwargs):  # noqa: D102
+    def success(self, *args, **kwargs):
         pass
 
 
@@ -357,9 +364,9 @@ class FlockLogger:
         self.min_level_severity = initial_min_level_severity
 
     def _get_logger(self):
-        if in_workflow_context():
-            # Use Temporal's workflow.logger inside a workflow context.
-            return workflow.logger
+        # if in_workflow_context():
+        #     # Use Temporal's workflow.logger inside a workflow context.
+        #     return workflow.logger
         # Bind our logger with category and trace_id
         return loguru_logger.bind(
             name=self.name,
@@ -371,9 +378,7 @@ class FlockLogger:
         """Truncate a message if it exceeds max_length and add truncation indicator."""
         if len(message) > max_length:
             truncated_chars = len(message) - max_length
-            return (
-                message[:max_length] + f"...<yellow>+({truncated_chars} chars)</yellow>"
-            )
+            return message[:max_length] + f"...<yellow>+({truncated_chars} chars)</yellow>"
         return message
 
     def debug(
@@ -385,8 +390,10 @@ class FlockLogger:
         **kwargs,
     ) -> None:
         current_method_severity = LOG_LEVELS["DEBUG"]
-        if self.min_level_severity == LOG_LEVELS["NO_LOGS"] or \
-           current_method_severity < self.min_level_severity:
+        if (
+            self.min_level_severity == LOG_LEVELS["NO_LOGS"]
+            or current_method_severity < self.min_level_severity
+        ):
             return
         """Debug a message.
 
@@ -407,8 +414,10 @@ class FlockLogger:
         **kwargs,
     ) -> None:
         current_method_severity = LOG_LEVELS["INFO"]
-        if self.min_level_severity == LOG_LEVELS["NO_LOGS"] or \
-           current_method_severity < self.min_level_severity:
+        if (
+            self.min_level_severity == LOG_LEVELS["NO_LOGS"]
+            or current_method_severity < self.min_level_severity
+        ):
             return
         """Info a message.
 
@@ -429,8 +438,10 @@ class FlockLogger:
         **kwargs,
     ) -> None:
         current_method_severity = LOG_LEVELS["WARNING"]
-        if self.min_level_severity == LOG_LEVELS["NO_LOGS"] or \
-           current_method_severity < self.min_level_severity:
+        if (
+            self.min_level_severity == LOG_LEVELS["NO_LOGS"]
+            or current_method_severity < self.min_level_severity
+        ):
             return
         """Warning a message.
 
@@ -451,8 +462,10 @@ class FlockLogger:
         **kwargs,
     ) -> None:
         current_method_severity = LOG_LEVELS["ERROR"]
-        if self.min_level_severity == LOG_LEVELS["NO_LOGS"] or \
-           current_method_severity < self.min_level_severity:
+        if (
+            self.min_level_severity == LOG_LEVELS["NO_LOGS"]
+            or current_method_severity < self.min_level_severity
+        ):
             return
         """Error a message.
 
@@ -472,9 +485,11 @@ class FlockLogger:
         max_length: int = MAX_LENGTH,
         **kwargs,
     ) -> None:
-        current_method_severity = LOG_LEVELS["ERROR"] # Exception implies ERROR level
-        if self.min_level_severity == LOG_LEVELS["NO_LOGS"] or \
-           current_method_severity < self.min_level_severity:
+        current_method_severity = LOG_LEVELS["ERROR"]  # Exception implies ERROR level
+        if (
+            self.min_level_severity == LOG_LEVELS["NO_LOGS"]
+            or current_method_severity < self.min_level_severity
+        ):
             return
         """Exception a message.
 
@@ -495,8 +510,10 @@ class FlockLogger:
         **kwargs,
     ) -> None:
         current_method_severity = LOG_LEVELS["SUCCESS"]
-        if self.min_level_severity == LOG_LEVELS["NO_LOGS"] or \
-           current_method_severity < self.min_level_severity:
+        if (
+            self.min_level_severity == LOG_LEVELS["NO_LOGS"]
+            or current_method_severity < self.min_level_severity
+        ):
             return
         """Success a message.
 
@@ -510,21 +527,22 @@ class FlockLogger:
 
 
 _LOGGER_CACHE: dict[str, FlockLogger] = {}
+_DEFAULT_FLOCK_SEVERITY: int = LOG_LEVELS["ERROR"]
+_SPECIFIC_SEVERITIES: dict[str, int] = {}
 
 
 def get_logger(name: str = "flock") -> FlockLogger:
     """Return a cached FlockLogger instance for the given name.
 
-    If the logger doesn't exist, it is created with 'enable_logging' set to False
-    by default (i.e., errors-only mode). Its state can then be changed by calling
-    the `configure_logging()` function.
+    If the logger doesn't exist, it is created using the configured severity level
+    from configure_logging() (default: ERROR). Respects specific_levels if configured.
     If a logger with the given name already exists in the cache, its 'min_level_severity'
     state is NOT modified by this function; it's simply returned.
     """
     if name not in _LOGGER_CACHE:
-        # New loggers default to errors-only (min_level_severity = ERROR_SEVERITY)
-        # until explicitly configured by configure_logging()
-        _LOGGER_CACHE[name] = FlockLogger(name, LOG_LEVELS["ERROR"])
+        # Check if there's a specific severity configured for this logger
+        severity = _SPECIFIC_SEVERITIES.get(name, _DEFAULT_FLOCK_SEVERITY)
+        _LOGGER_CACHE[name] = FlockLogger(name, severity)
     # The min_level_severity state of existing or newly created loggers
     # should be managed by the configure_logging() function.
     return _LOGGER_CACHE[name]
@@ -544,15 +562,13 @@ def truncate_for_logging(obj, max_item_length=100, max_items=10):
     """Truncate large data structures for logging purposes."""
     if isinstance(obj, str) and len(obj) > max_item_length:
         return obj[:max_item_length] + f"... ({len(obj) - max_item_length} more chars)"
-    elif isinstance(obj, dict):
+    if isinstance(obj, dict):
         if len(obj) > max_items:
             return {
-                k: truncate_for_logging(v)
-                for i, (k, v) in enumerate(obj.items())
-                if i < max_items
+                k: truncate_for_logging(v) for i, (k, v) in enumerate(obj.items()) if i < max_items
             }
         return {k: truncate_for_logging(v) for k, v in obj.items()}
-    elif isinstance(obj, list):
+    if isinstance(obj, list):
         if len(obj) > max_items:
             return [truncate_for_logging(item) for item in obj[:max_items]] + [
                 f"... ({len(obj) - max_items} more items)"

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",
+]