Merge branch 'develop' of https://github.com/evolution-foundation/evo-ai-processor-community into develop

Author: DavidsonGomes

src/evo_extension_points/__init__.py

@@ -0,0 +1,23 @@
+"""Public extension contract of evo-ai-processor-community.
+
+See ``EXTENSION_POINTS.md`` at the repository root for the full contract.
+Each extension point is versioned independently via its own ``VERSION``
+attribute; there is no aggregate version constant.
+"""
+
+from __future__ import annotations
+
+from . import capability_gate, runtime_context, usage_reporter
+from .registry import KNOWN_KEYS, impl_for, replace, reset
+from .usage_reporter import ExecutionMetrics
+
+__all__ = [
+    "ExecutionMetrics",
+    "KNOWN_KEYS",
+    "capability_gate",
+    "impl_for",
+    "replace",
+    "reset",
+    "runtime_context",
+    "usage_reporter",
+]

src/evo_extension_points/capability_gate.py

@@ -0,0 +1,37 @@
+"""CapabilityGate extension point.
+
+Community default: every capability is enabled. A consumer overrides via
+``evo_extension_points.replace("capability_gate", impl)`` where ``impl``
+is any object whose attributes satisfy the ``CapabilityGate`` Protocol.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from . import registry
+
+VERSION: str = "1.0.0"
+
+
+@runtime_checkable
+class CapabilityGate(Protocol):
+    def is_enabled(
+        self, capability: str, *, context: dict[str, Any] | None = None
+    ) -> bool: ...
+
+
+class _DefaultCapabilityGate:
+    def is_enabled(
+        self, capability: str, *, context: dict[str, Any] | None = None
+    ) -> bool:
+        return True
+
+
+_DEFAULT = _DefaultCapabilityGate()
+registry._register_protocol("capability_gate", CapabilityGate)
+
+
+def is_enabled(capability: str, *, context: dict[str, Any] | None = None) -> bool:
+    impl = registry.impl_for("capability_gate") or _DEFAULT
+    return impl.is_enabled(capability, context=context)

src/evo_extension_points/registry.py

@@ -0,0 +1,51 @@
+"""In-memory override registry shared by the three extension points.
+
+The Registration API is itself part of the public contract — see
+``EXTENSION_POINTS.md`` at the repository root for the full specification.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Final
+
+KNOWN_KEYS: Final[frozenset[str]] = frozenset(
+    {"capability_gate", "runtime_context", "usage_reporter"}
+)
+
+_PROTOCOLS: dict[str, type] = {}
+_registry: dict[str, Any] = {}
+_lock = threading.RLock()
+
+
+def _register_protocol(name: str, protocol: type) -> None:
+    if name not in KNOWN_KEYS:
+        raise KeyError(f"unknown extension point: {name!r}")
+    _PROTOCOLS[name] = protocol
+
+
+def replace(name: str, impl: object) -> None:
+    if name not in KNOWN_KEYS:
+        raise KeyError(f"unknown extension point: {name!r}")
+    if impl is None:
+        raise TypeError(
+            f"impl for {name!r} must not be None; use reset({name!r}) instead"
+        )
+    protocol = _PROTOCOLS.get(name)
+    if protocol is not None and not isinstance(impl, protocol):
+        raise TypeError(
+            f"impl for {name!r} does not satisfy {protocol.__name__}"
+        )
+    with _lock:
+        _registry[name] = impl
+
+
+def reset(name: str) -> None:
+    if name not in KNOWN_KEYS:
+        raise KeyError(f"unknown extension point: {name!r}")
+    with _lock:
+        _registry.pop(name, None)
+
+
+def impl_for(name: str) -> Any | None:
+    return _registry.get(name)

src/evo_extension_points/runtime_context.py

@@ -0,0 +1,45 @@
+"""RuntimeContext extension point.
+
+Community default: ``current_context_id`` returns ``None``;
+``with_context`` yields the callable's result without binding any state
+(single-scope mode).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Protocol, TypeVar, runtime_checkable
+
+from . import registry
+
+VERSION: str = "1.0.0"
+
+T = TypeVar("T")
+
+
+@runtime_checkable
+class RuntimeContext(Protocol):
+    def current_context_id(self, source: Any) -> str | None: ...
+
+    def with_context(self, context_id: str, fn: Callable[[], T]) -> T: ...
+
+
+class _DefaultRuntimeContext:
+    def current_context_id(self, source: Any) -> str | None:
+        return None
+
+    def with_context(self, context_id: str, fn: Callable[[], T]) -> T:
+        return fn()
+
+
+_DEFAULT = _DefaultRuntimeContext()
+registry._register_protocol("runtime_context", RuntimeContext)
+
+
+def current_context_id(source: Any = None) -> str | None:
+    impl = registry.impl_for("runtime_context") or _DEFAULT
+    return impl.current_context_id(source)
+
+
+def with_context(context_id: str, fn: Callable[[], T]) -> T:
+    impl = registry.impl_for("runtime_context") or _DEFAULT
+    return impl.with_context(context_id, fn)

src/evo_extension_points/usage_reporter.py

@@ -0,0 +1,45 @@
+"""UsageReporter extension point.
+
+Community default: no-op. The processor always persists each execution
+into ``evo_agent_processor_execution_metrics`` locally and then calls
+``report_execution`` with the same data; the default discards the call.
+A consumer registers a non-default implementation to mirror the local
+table into external observability.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+from . import registry
+
+VERSION: str = "1.0.0"
+
+
+@dataclass(frozen=True)
+class ExecutionMetrics:
+    execution_id: str
+    prompt_tokens: int
+    candidate_tokens: int
+    total_tokens: int
+    cost: float
+
+
+@runtime_checkable
+class UsageReporter(Protocol):
+    def report_execution(self, metrics: ExecutionMetrics) -> None: ...
+
+
+class _DefaultUsageReporter:
+    def report_execution(self, metrics: ExecutionMetrics) -> None:
+        return None
+
+
+_DEFAULT = _DefaultUsageReporter()
+registry._register_protocol("usage_reporter", UsageReporter)
+
+
+def report_execution(metrics: ExecutionMetrics) -> None:
+    impl = registry.impl_for("usage_reporter") or _DEFAULT
+    impl.report_execution(metrics)

src/services/adk/runners/standard_runner.py

@@ -37,6 +37,13 @@
 from typing import Optional, Dict, Any
 from src.services.session_service import create_execution_metrics
 from src.schemas.schemas import ExecutionMetricsCreate
+from src.evo_extension_points import (
+    ExecutionMetrics,
+    capability_gate,
+    impl_for as ep_impl_for,
+    runtime_context,
+    usage_reporter,
+)
 import uuid
 
 logger = setup_logger(__name__)
@@ -69,6 +76,34 @@ async def run_agent(
                 f"Starting execution of agent {agent_id} for external_id {external_id}"
             )
 
+            # Extension point: capability gate. Community default returns True
+            # for every capability, so behavior is unchanged unless a consumer
+            # mounts a denying gate. Denial short-circuits with a structured
+            # error code rather than a fake agent reply.
+            capability = (metadata or {}).get("capability")
+            if capability and not capability_gate.is_enabled(
+                capability, context=metadata
+            ):
+                logger.warning(
+                    f"capability_gate denied capability={capability!r} for"
+                    f" agent={agent_id} external_id={external_id}"
+                )
+                return {
+                    "error": "capability_denied",
+                    "capability": capability,
+                    "message_history": [],
+                }
+
+            # Extension point: runtime context resolution. Default returns
+            # None; consumer overrides return an operational context id that
+            # is logged here and (in a follow-up) propagated into metrics.
+            context_id = runtime_context.current_context_id(metadata)
+            if context_id:
+                logger.info(
+                    f"runtime_context resolved id={context_id!r}"
+                    f" for agent={agent_id}"
+                )
+
             # Get and build agent
             root_agent, state_params = await self.utils.get_and_build_agent(agent_id)
 
@@ -471,6 +506,27 @@ async def run_agent(
                 except Exception as e:
                     logger.error(f"Error creating execution metrics: {e}")
 
+                # Extension point: usage reporter. Always called after the
+                # local persistence above; default is a no-op. A misbehaving
+                # consumer cannot break the run — we swallow the exception
+                # and log with full context.
+                try:
+                    usage_reporter.report_execution(
+                        ExecutionMetrics(
+                            execution_id=adk_session_id,
+                            prompt_tokens=total_prompt_tokens,
+                            candidate_tokens=total_candidate_tokens,
+                            total_tokens=total_tokens,
+                            cost=0.0,
+                        )
+                    )
+                except Exception:
+                    logger.exception(
+                        "usage_reporter.report_execution failed for"
+                        f" execution_id={adk_session_id!r}"
+                        f" impl={ep_impl_for('usage_reporter')!r}"
+                    )
+
             except Exception as e:
                 logger.error(f"Error processing request: {str(e)}")
                 raise InternalServerError(str(e)) from e