fast-agent-mcp 0.4.7__py3-none-any.whl

fast_agent/constants.py

@@ -0,0 +1,41 @@
+"""
+Global constants for fast_agent with minimal dependencies to avoid circular imports.
+"""
+
+# Canonical tool name for the human input/elicitation tool
+HUMAN_INPUT_TOOL_NAME = "__human_input"
+MCP_UI = "mcp-ui"
+REASONING = "reasoning"
+FAST_AGENT_ERROR_CHANNEL = "fast-agent-error"
+FAST_AGENT_REMOVED_METADATA_CHANNEL = "fast-agent-removed-meta"
+FAST_AGENT_TIMING = "fast-agent-timing"
+FAST_AGENT_TOOL_TIMING = "fast-agent-tool-timing"
+# should we have MAX_TOOL_CALLS instead to constrain by number of tools rather than turns...?
+DEFAULT_MAX_ITERATIONS = 99
+"""Maximum number of User/Assistant turns to take"""
+
+DEFAULT_TERMINAL_OUTPUT_BYTE_LIMIT = 8192
+"""Baseline byte limit for ACP terminal output when no model info exists."""
+
+TERMINAL_OUTPUT_TOKEN_RATIO = 0.25
+"""Target fraction of model max output tokens to budget for terminal output."""
+
+TERMINAL_OUTPUT_TOKEN_HEADROOM_RATIO = 0.2
+"""Leave headroom for tool wrapper text and other turn data."""
+
+TERMINAL_AVG_BYTES_PER_TOKEN = 4
+"""Conservative bytes-per-token estimate for mapping token budgets to byte limits."""
+
+MAX_TERMINAL_OUTPUT_BYTE_LIMIT = 32768
+"""Hard cap on default ACP terminal output to avoid oversized tool payloads."""
+
+DEFAULT_AGENT_INSTRUCTION = """You are a helpful AI Agent.
+
+{{serverInstructions}}
+{{agentSkills}}
+{{file_silent:AGENTS.md}}
+{{env}}
+
+The current date is {{currentDate}}."""
+
+CONTROL_MESSAGE_SAVE_HISTORY = "***SAVE_HISTORY"

fast_agent/context.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import logging
+import uuid
+from os import PathLike
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+
+# from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor
+from opentelemetry.propagate import set_global_textmap
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+from pydantic import BaseModel, ConfigDict
+
+from fast_agent.config import Settings, get_settings
+from fast_agent.core.executor.executor import AsyncioExecutor, Executor
+from fast_agent.core.executor.task_registry import ActivityRegistry
+from fast_agent.core.logging.events import EventFilter, StreamingExclusionFilter
+from fast_agent.core.logging.logger import LoggingConfig, get_logger
+from fast_agent.core.logging.transport import create_transport
+from fast_agent.mcp_server_registry import ServerRegistry
+from fast_agent.skills import SkillRegistry
+
+if TYPE_CHECKING:
+    from fast_agent.acp.acp_context import ACPContext
+    from fast_agent.core.executor.workflow_signal import SignalWaitCallback
+    from fast_agent.mcp.mcp_connection_manager import MCPConnectionManager
+else:
+    # Runtime placeholders for the types
+    ACPContext = Any
+    SignalWaitCallback = Any
+    MCPConnectionManager = Any
+
+logger = get_logger(__name__)
+
+"""
+A central context object to store global state that is shared across the application.
+"""
+
+
+class Context(BaseModel):
+    """
+    Context that is passed around through the application.
+    This is a global context that is shared across the application.
+    """
+
+    config: Settings | None = None
+    executor: Executor | None = None
+    human_input_handler: Any | None = None
+    signal_notification: SignalWaitCallback | None = None
+
+    # Registries
+    server_registry: ServerRegistry | None = None
+    task_registry: ActivityRegistry | None = None
+    skill_registry: SkillRegistry | None = None
+
+    tracer: trace.Tracer | None = None
+    _connection_manager: "MCPConnectionManager | None" = None
+
+    # ACP context - set when running in ACP mode
+    # Provides agents access to ACP capabilities (mode switching, commands, etc.)
+    acp: "ACPContext | None" = None
+
+    model_config = ConfigDict(
+        extra="allow",
+        arbitrary_types_allowed=True,  # Tell Pydantic to defer type evaluation
+    )
+
+
+async def configure_otel(config: "Settings") -> None:
+    """
+    Configure OpenTelemetry based on the application config.
+    """
+    if not config.otel or not config.otel.enabled:
+        return
+
+    # Set up global textmap propagator first
+    set_global_textmap(TraceContextTextMapPropagator())
+
+    service_name = config.otel.service_name
+    from importlib.metadata import version
+
+    try:
+        app_version = version("fast-agent-mcp")
+    except:  # noqa: E722
+        app_version = "unknown"
+
+    resource = Resource.create(
+        attributes={
+            key: value
+            for key, value in {
+                "service.name": service_name,
+                "service.instance.id": str(uuid.uuid4())[:6],
+                "service.version": app_version,
+            }.items()
+            if value is not None
+        }
+    )
+
+    # Create provider with resource
+    tracer_provider = TracerProvider(resource=resource)
+
+    # Add exporters based on config
+    otlp_endpoint = config.otel.otlp_endpoint
+    if otlp_endpoint:
+        exporter = OTLPSpanExporter(endpoint=otlp_endpoint)
+        tracer_provider.add_span_processor(BatchSpanProcessor(exporter))
+
+        if config.otel.console_debug:
+            tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
+    else:
+        # Default to console exporter in development
+        tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
+
+    # Set as global tracer provider
+    trace.set_tracer_provider(tracer_provider)
+
+    # Attempt to instrument optional SDKs if available; continue silently if missing
+    try:
+        from opentelemetry.instrumentation.openai import OpenAIInstrumentor
+
+        OpenAIInstrumentor().instrument()
+    except Exception:  # pragma: no cover - optional instrumentation
+        pass
+
+    try:
+        from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor
+
+        GoogleGenAiSdkInstrumentor().instrument()
+    except Exception:  # pragma: no cover - optional instrumentation
+        pass
+
+
+#   McpInstrumentor().instrument()
+
+
+async def configure_logger(config: "Settings") -> None:
+    """
+    Configure logging and tracing based on the application config.
+    """
+    settings = config.logger
+
+    # Configure the standard Python logger used by LoggingListener so it respects settings.
+    python_logger = logging.getLogger("fast_agent")
+    python_logger.handlers.clear()
+    python_logger.setLevel(settings.level.upper())
+    python_logger.propagate = False
+
+    transport = None
+    if settings.type == "console":
+        # Console mode: use the Python logger to emit to stdout and skip additional transport output
+        handler = logging.StreamHandler()
+        handler.setLevel(settings.level.upper())
+        handler.setFormatter(logging.Formatter("%(message)s"))
+        python_logger.addHandler(handler)
+    else:
+        # For all other modes, rely on transports (file/http/none) and keep the Python logger quiet
+        python_logger.addHandler(logging.NullHandler())
+
+    # Use StreamingExclusionFilter to prevent streaming events from flooding logs
+    event_filter: EventFilter = StreamingExclusionFilter(min_level=settings.level)
+    logger.info(f"Configuring logger with level: {settings.level}")
+    if settings.type == "console":
+        from fast_agent.core.logging.transport import NoOpTransport
+
+        transport = NoOpTransport(event_filter=event_filter)
+    else:
+        transport = create_transport(settings=settings, event_filter=event_filter)
+    await LoggingConfig.configure(
+        event_filter=event_filter,
+        transport=transport,
+        batch_size=settings.batch_size,
+        flush_interval=settings.flush_interval,
+        progress_display=settings.progress_display,
+    )
+
+
+async def configure_executor(config: "Settings"):
+    """
+    Configure the executor based on the application config.
+    """
+    return AsyncioExecutor()
+
+
+async def initialize_context(
+    config: Settings | str | PathLike[str] | None = None, store_globally: bool = False
+):
+    """
+    Initialize the global application context.
+    """
+    if config is None:
+        config = get_settings()
+    elif isinstance(config, (str, PathLike)):
+        # Accept pathlib.Path and other path-like objects for convenience in tests
+        config = get_settings(config_path=str(config))
+
+    context = Context()
+    context.config = config
+    context.server_registry = ServerRegistry(config=config)
+
+    skills_settings = getattr(config, "skills", None)
+    override_directory = None
+    if skills_settings and getattr(skills_settings, "directory", None):
+        override_directory = Path(skills_settings.directory).expanduser()
+    context.skill_registry = SkillRegistry(
+        base_dir=Path.cwd(),
+        override_directory=override_directory,
+    )
+
+    # Configure logging and telemetry
+    await configure_otel(config)
+    await configure_logger(config)
+
+    # Configure the executor
+    context.executor = await configure_executor(config)
+    context.task_registry = ActivityRegistry()
+
+    # Store the tracer in context if needed
+    if config.otel:
+        context.tracer = trace.get_tracer(config.otel.service_name)
+
+    if store_globally:
+        global _global_context
+        _global_context = context
+
+    return context
+
+
+async def cleanup_context() -> None:
+    """
+    Cleanup the global application context.
+    """
+
+    # Shutdown logging and telemetry
+    await LoggingConfig.shutdown()
+
+
+_global_context: Context | None = None
+
+
+def get_current_context() -> Context:
+    """
+    Synchronous initializer/getter for global application context.
+    """
+    global _global_context
+    if _global_context is None:
+        try:
+            # Try to get the current event loop
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                # Create a new loop in a separate thread
+                def run_async():
+                    new_loop = asyncio.new_event_loop()
+                    asyncio.set_event_loop(new_loop)
+                    return new_loop.run_until_complete(initialize_context())
+
+                with concurrent.futures.ThreadPoolExecutor() as pool:
+                    _global_context = pool.submit(run_async).result()
+            else:
+                _global_context = loop.run_until_complete(initialize_context())
+        except RuntimeError:
+            _global_context = asyncio.run(initialize_context())
+    return _global_context
+
+
+def get_current_config():
+    """
+    Get the current application config.
+
+    Returns the context config if available, otherwise falls back to global settings.
+    """
+    return get_current_context().config or get_settings()

fast_agent/context_dependent.py

@@ -0,0 +1,50 @@
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from fast_agent.context import Context
+
+
+class ContextDependent:
+    """
+    Mixin class for components that need context access.
+    Provides both global fallback and instance-specific context support.
+    """
+
+    # Ensure the attribute always exists even if a subclass
+    # does not call this mixin's __init__.
+    _context: "Context | None" = None
+
+    def __init__(self, context: "Context | None" = None, **kwargs: dict[str, Any]) -> None:
+        self._context = context
+        super().__init__()
+
+    @property
+    def context(self) -> "Context":
+        """
+        Get context, with graceful fallback to global context if needed.
+        Raises clear error if no context is available.
+        """
+        # First try instance context
+        if self._context is not None:
+            return self._context
+
+        try:
+            # Fall back to global context if available
+            from fast_agent.context import get_current_context
+
+            return get_current_context()
+        except Exception as e:
+            raise RuntimeError(
+                f"No context available for {self.__class__.__name__}. Either initialize Core first or pass context explicitly."
+            ) from e
+
+    @contextmanager
+    def use_context(self, context: "Context"):
+        """Temporarily use a different context."""
+        old_context = self._context
+        self._context = context
+        try:
+            yield
+        finally:
+            self._context = old_context

fast_agent/core/__init__.py

@@ -0,0 +1,92 @@
+"""
+Core interfaces and decorators for fast-agent.
+
+Public API:
+- `Core`: The core application container
+- `AgentApp`: Container for interacting with agents
+- `FastAgent`: High-level, decorator-driven application class
+- Decorators: `agent`, `custom`, `orchestrator`, `iterative_planner`,
+  `router`, `chain`, `parallel`, `evaluator_optimizer`
+
+Exports are resolved lazily to avoid circular imports during package init.
+"""
+
+from typing import TYPE_CHECKING
+
+
+def __getattr__(name: str):
+    if name == "AgentApp":
+        from .agent_app import AgentApp
+
+        return AgentApp
+    elif name == "Core":
+        from .core_app import Core
+
+        return Core
+    elif name == "FastAgent":
+        from .fastagent import FastAgent
+
+        return FastAgent
+    elif name in (
+        "agent",
+        "custom",
+        "orchestrator",
+        "iterative_planner",
+        "router",
+        "chain",
+        "parallel",
+        "evaluator_optimizer",
+    ):
+        from . import direct_decorators as _dd
+
+        return getattr(
+            _dd,
+            name,
+        )
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+if TYPE_CHECKING:  # pragma: no cover - typing aid only
+    from .agent_app import AgentApp as AgentApp  # noqa: F401
+    from .core_app import Core as Core  # noqa: F401
+    from .direct_decorators import (  # noqa: F401
+        agent as agent,
+    )
+    from .direct_decorators import (
+        chain as chain,
+    )
+    from .direct_decorators import (
+        custom as custom,
+    )
+    from .direct_decorators import (
+        evaluator_optimizer as evaluator_optimizer,
+    )
+    from .direct_decorators import (
+        iterative_planner as iterative_planner,
+    )
+    from .direct_decorators import (
+        orchestrator as orchestrator,
+    )
+    from .direct_decorators import (
+        parallel as parallel,
+    )
+    from .direct_decorators import (
+        router as router,
+    )
+    from .fastagent import FastAgent as FastAgent  # noqa: F401
+
+
+__all__ = [
+    "Core",
+    "AgentApp",
+    "FastAgent",
+    # Decorators
+    "agent",
+    "custom",
+    "orchestrator",
+    "iterative_planner",
+    "router",
+    "chain",
+    "parallel",
+    "evaluator_optimizer",
+]