digitalkin 0.3.1.dev2__py3-none-any.whl → 0.3.2.dev14__py3-none-any.whl

modules/archetype_with_tools_module.py

@@ -0,0 +1,244 @@
+"""Example archetype module with tool cache integration."""
+
+import logging
+from typing import Any, ClassVar, Literal
+
+from pydantic import BaseModel, Field
+
+from digitalkin.models.grpc_servers.models import ClientConfig, SecurityMode, ServerMode
+from digitalkin.models.module.module_context import ModuleContext
+from digitalkin.models.module.setup_types import SetupModel
+from digitalkin.models.module.tool_reference import (
+    ToolReference,
+    ToolReferenceConfig,
+    ToolSelectionMode,
+)
+from digitalkin.modules._base_module import BaseModule  # noqa: PLC2701
+from digitalkin.services.services_models import ServicesStrategy
+
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+class MessageInputPayload(BaseModel):
+    """Message input payload."""
+
+    payload_type: Literal["message"] = "message"
+    user_prompt: str
+
+
+class ArchetypeInput(BaseModel):
+    """Archetype input."""
+
+    payload: MessageInputPayload = Field(discriminator="payload_type")
+
+
+class MessageOutputPayload(BaseModel):
+    """Message output payload."""
+
+    payload_type: Literal["message"] = "message"
+    response: str
+    tools_used: list[str] = Field(default_factory=list)
+
+
+class ArchetypeOutput(BaseModel):
+    """Archetype output."""
+
+    payload: MessageOutputPayload = Field(discriminator="payload_type")
+
+
+class ArchetypeSetup(SetupModel):
+    """Setup with tool references resolved during config setup."""
+
+    model_name: str = Field(
+        default="gpt-4",
+        json_schema_extra={"config": True},
+    )
+    temperature: float = Field(
+        default=0.7,
+        json_schema_extra={"config": True},
+    )
+
+    search_tool: ToolReference = Field(
+        default_factory=lambda: ToolReference(
+            config=ToolReferenceConfig(
+                mode=ToolSelectionMode.FIXED,
+                module_id="search-tool-v1",
+            )
+        ),
+        json_schema_extra={"config": True},
+    )
+
+    calculator_tool: ToolReference = Field(
+        default_factory=lambda: ToolReference(
+            config=ToolReferenceConfig(
+                mode=ToolSelectionMode.TAG,
+                tag="math-calculator",
+            )
+        ),
+        json_schema_extra={"config": True},
+    )
+
+    dynamic_tool: ToolReference = Field(
+        default_factory=lambda: ToolReference(
+            config=ToolReferenceConfig(
+                mode=ToolSelectionMode.DISCOVERABLE,
+            )
+        ),
+        json_schema_extra={"config": True},
+    )
+
+    system_prompt: str = Field(
+        default="You are a helpful assistant with access to tools.",
+        json_schema_extra={"hidden": True},
+    )
+
+
+class ArchetypeConfigSetup(BaseModel):
+    """Config setup model."""
+
+    additional_instructions: str | None = None
+
+
+class ArchetypeSecret(BaseModel):
+    """Secrets model."""
+
+
+client_config = ClientConfig(
+    host="[::]",
+    port=50152,
+    mode=ServerMode.ASYNC,
+    security=SecurityMode.INSECURE,
+    credentials=None,
+)
+
+
+class ArchetypeWithToolsModule(
+    BaseModule[
+        ArchetypeInput,
+        ArchetypeOutput,
+        ArchetypeSetup,
+        ArchetypeSecret,
+    ]
+):
+    """Archetype module demonstrating tool cache usage."""
+
+    name = "ArchetypeWithToolsModule"
+    description = "Archetype with tool cache integration"
+
+    config_setup_format = ArchetypeConfigSetup
+    input_format = ArchetypeInput
+    output_format = ArchetypeOutput
+    setup_format = ArchetypeSetup
+    secret_format = ArchetypeSecret
+
+    metadata: ClassVar[dict[str, Any]] = {
+        "name": "ArchetypeWithToolsModule",
+        "version": "1.0.0",
+        "tags": ["archetype", "tools"],
+    }
+
+    services_config_strategies: ClassVar[dict[str, ServicesStrategy | None]] = {}
+    services_config_params: ClassVar[dict[str, dict[str, Any | None] | None]] = {
+        "registry": {
+            "config": {},
+            "client_config": client_config,
+        },
+    }
+
+    async def run_config_setup(
+        self,
+        context: ModuleContext,  # noqa: ARG002
+        config_setup_data: ArchetypeSetup,
+    ) -> ArchetypeSetup:
+        """Custom config setup logic, runs in parallel with tool resolution.
+
+        Args:
+            context: Module context with services.
+            config_setup_data: Setup data being configured.
+
+        Returns:
+            Configured setup data.
+        """
+        logger.info("Running config setup for %s", self.name)
+        return config_setup_data
+
+    async def initialize(self, context: ModuleContext, setup_data: ArchetypeSetup) -> None:  # noqa: ARG002
+        """Initialize module.
+
+        Args:
+            context: Module context with services and tool cache.
+            setup_data: Setup data for the module.
+        """
+        logger.info("Initializing %s", self.name)
+        if context.tool_cache:
+            logger.info("Available tools: %s", context.tool_cache.list_tools())
+
+    async def run(
+        self,
+        input_data: ArchetypeInput,
+        setup_data: ArchetypeSetup,  # noqa: ARG002
+    ) -> None:
+        """Run module with tool cache lookups and call_module_by_id.
+
+        Args:
+            input_data: Input data to process.
+            setup_data: Setup configuration.
+        """
+        logger.info("Running %s", self.name)
+
+        tools_used: list[str] = []
+        tool_results: list[str] = []
+
+        # Get search tool from cache and call via call_module_by_id
+        search_info = self.context.tool_cache.get("search_tool")
+        if search_info:
+            tools_used.append(f"search:{search_info.module_id}")
+            async for response in self.context.call_module_by_id(
+                module_id=search_info.module_id,
+                input_data={"query": input_data.payload.user_prompt},
+                setup_id=self.context.session.setup_id,
+                mission_id=self.context.session.mission_id,
+            ):
+                tool_results.append(f"search_result: {response}")
+
+        # Get calculator tool from cache
+        calc_info = self.context.tool_cache.get("calculator_tool")
+        if calc_info:
+            tools_used.append(f"calculator:{calc_info.module_id}")
+            async for response in self.context.call_module_by_id(
+                module_id=calc_info.module_id,
+                input_data={"expression": "2 + 2"},
+                setup_id=self.context.session.setup_id,
+                mission_id=self.context.session.mission_id,
+            ):
+                tool_results.append(f"calc_result: {response}")
+
+        # Dynamic discovery via registry fallback for tools not in cache
+        dynamic_info = self.context.tool_cache.get(
+            "some_dynamic_tool",
+            registry=self.context.registry,
+        )
+        if dynamic_info:
+            tools_used.append(f"dynamic:{dynamic_info.module_id}")
+            async for response in self.context.call_module_by_id(
+                module_id=dynamic_info.module_id,
+                input_data={"prompt": input_data.payload.user_prompt},
+                setup_id=self.context.session.setup_id,
+                mission_id=self.context.session.mission_id,
+            ):
+                tool_results.append(f"dynamic_result: {response}")
+
+        response = MessageOutputPayload(
+            response=f"Processed: {input_data.payload.user_prompt} | Results: {len(tool_results)}",
+            tools_used=tools_used,
+        )
+
+        await self.context.callbacks.send_message(ArchetypeOutput(payload=response))
+
+    async def cleanup(self) -> None:
+        """Clean up resources."""
+        logger.info("Cleaning up %s", self.name)

modules/cpu_intensive_module.py

@@ -4,9 +4,9 @@ import logging
 from collections.abc import Callable
 from typing import Any, ClassVar, Literal
 
+from digitalkin.grpc_servers.utils.models import ClientConfig, SecurityMode, ServerConfig, ServerMode
 from pydantic import BaseModel, Field
 
-from digitalkin.grpc_servers.utils.models import ClientConfig, SecurityMode, ServerConfig, ServerMode
 from digitalkin.modules._base_module import BaseModule
 from digitalkin.services.services_models import ServicesStrategy
 from digitalkin.services.setup.setup_strategy import SetupData

modules/dynamic_setup_module.py

@@ -209,8 +209,6 @@ class DynamicModuleOutput(DataModel[MessageOutputTrigger]):
 class DynamicModuleSecret(BaseModel):
     """Secret model (empty for this example)."""
 
-    pass
-
 
 # =============================================================================
 # Module Implementation
@@ -285,13 +283,7 @@ class DynamicSetupModule(
 
 async def demonstrate_dynamic_schema() -> None:
     """Demonstrate the dynamic schema functionality."""
-    print("=" * 60)
-    print("Dynamic Schema Demonstration")
-    print("=" * 60)
-
     # 1. Show schema WITHOUT force (dynamic fields not resolved)
-    print("\n1. Schema without force=True (fetchers NOT called):")
-    print("-" * 40)
 
     model_no_force = await DynamicAgentSetup.get_clean_model(
         config_fields=True,
@@ -302,13 +294,10 @@ async def demonstrate_dynamic_schema() -> None:
 
     # Check if enum is present
     model_name_schema = schema_no_force.get("properties", {}).get("model_name", {})
-    print(f"model_name has enum: {'enum' in model_name_schema}")
     if "enum" in model_name_schema:
-        print(f"  enum values: {model_name_schema['enum']}")
+        pass
 
     # 2. Show schema WITH force (dynamic fields resolved)
-    print("\n2. Schema with force=True (fetchers called):")
-    print("-" * 40)
 
     model_with_force = await DynamicAgentSetup.get_clean_model(
         config_fields=True,
@@ -319,43 +308,30 @@ async def demonstrate_dynamic_schema() -> None:
 
     # Check enum values after force
     model_name_schema = schema_with_force.get("properties", {}).get("model_name", {})
-    print(f"model_name has enum: {'enum' in model_name_schema}")
     if "enum" in model_name_schema:
-        print(f"  enum values: {model_name_schema['enum']}")
+        pass
 
     language_schema = schema_with_force.get("properties", {}).get("language", {})
-    print(f"language has enum: {'enum' in language_schema}")
     if "enum" in language_schema:
-        print(f"  enum values: {language_schema['enum']}")
+        pass
 
     # 3. Show that static json_schema_extra is preserved
-    print("\n3. Static json_schema_extra preserved:")
-    print("-" * 40)
-    print(f"model_name ui:widget: {model_name_schema.get('ui:widget', 'NOT FOUND')}")
 
     # 4. Show field filtering
-    print("\n4. Field filtering demonstration:")
-    print("-" * 40)
 
     # Config fields only (hidden excluded)
-    config_model = await DynamicAgentSetup.get_clean_model(
+    await DynamicAgentSetup.get_clean_model(
         config_fields=True,
         hidden_fields=False,
         force=False,
     )
-    print(f"Config fields (hidden=False): {list(config_model.model_fields.keys())}")
 
     # All fields including hidden
-    all_model = await DynamicAgentSetup.get_clean_model(
+    await DynamicAgentSetup.get_clean_model(
         config_fields=True,
         hidden_fields=True,
         force=False,
     )
-    print(f"All fields (hidden=True): {list(all_model.model_fields.keys())}")
-
-    print("\n" + "=" * 60)
-    print("Demonstration complete!")
-    print("=" * 60)
 
 
 if __name__ == "__main__":

modules/minimal_llm_module.py

@@ -6,9 +6,9 @@ from collections.abc import Callable
 from typing import Any, ClassVar, Literal
 
 import openai
+from digitalkin.grpc_servers.utils.models import ClientConfig, SecurityMode, ServerMode
 from pydantic import BaseModel, Field
 
-from digitalkin.grpc_servers.utils.models import ClientConfig, SecurityMode, ServerMode
 from digitalkin.modules._base_module import BaseModule
 from digitalkin.services.services_models import ServicesStrategy
 

modules/text_transform_module.py

@@ -4,9 +4,9 @@ import logging
 from collections.abc import Callable
 from typing import Any, ClassVar
 
+from digitalkin.grpc_servers.utils.models import ClientConfig, SecurityMode, ServerMode
 from pydantic import BaseModel
 
-from digitalkin.grpc_servers.utils.models import ClientConfig, SecurityMode, ServerMode
 from digitalkin.modules._base_module import BaseModule
 from digitalkin.services.setup.setup_strategy import SetupData
 from digitalkin.services.storage.storage_strategy import DataType, StorageRecord

monitoring/digitalkin_observability/__init__.py

@@ -0,0 +1,46 @@
+"""Standalone observability module for DigitalKin.
+
+This module can be copied into your project and used independently.
+It has no dependencies on the digitalkin package.
+
+Usage:
+    from digitalkin_observability import (
+        MetricsCollector,
+        MetricsServer,
+        MetricsServerInterceptor,
+        PrometheusExporter,
+        get_metrics,
+        start_metrics_server,
+        stop_metrics_server,
+    )
+
+    # Start metrics HTTP server
+    start_metrics_server(port=8081)
+
+    # Track metrics
+    metrics = get_metrics()
+    metrics.inc_jobs_started("my_module")
+    metrics.inc_jobs_completed("my_module", duration=1.5)
+
+    # Export to Prometheus format
+    print(PrometheusExporter.export())
+"""
+
+from digitalkin_observability.http_server import (
+    MetricsServer,
+    start_metrics_server,
+    stop_metrics_server,
+)
+from digitalkin_observability.interceptors import MetricsServerInterceptor
+from digitalkin_observability.metrics import MetricsCollector, get_metrics
+from digitalkin_observability.prometheus import PrometheusExporter
+
+__all__ = [
+    "MetricsCollector",
+    "MetricsServer",
+    "MetricsServerInterceptor",
+    "PrometheusExporter",
+    "get_metrics",
+    "start_metrics_server",
+    "stop_metrics_server",
+]

monitoring/digitalkin_observability/http_server.py

@@ -0,0 +1,150 @@
+"""Simple HTTP server for exposing Prometheus metrics.
+
+This module provides an HTTP server that exposes metrics at /metrics endpoint.
+No external dependencies required beyond Python standard library.
+"""
+
+from __future__ import annotations
+
+import logging
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from threading import Thread
+from typing import TYPE_CHECKING, ClassVar
+
+if TYPE_CHECKING:
+    from typing import Self
+
+logger = logging.getLogger(__name__)
+
+
+class MetricsHandler(BaseHTTPRequestHandler):
+    """HTTP request handler for metrics endpoint."""
+
+    def do_GET(self) -> None:
+        """Handle GET requests."""
+        if self.path == "/metrics":
+            self._serve_metrics()
+        elif self.path == "/health":
+            self._serve_health()
+        else:
+            self.send_error(404, "Not Found")
+
+    def _serve_metrics(self) -> None:
+        """Serve Prometheus metrics."""
+        from digitalkin_observability.prometheus import PrometheusExporter
+
+        content = PrometheusExporter.export()
+        self.send_response(200)
+        self.send_header("Content-Type", "text/plain; charset=utf-8")
+        self.send_header("Content-Length", str(len(content)))
+        self.end_headers()
+        self.wfile.write(content.encode("utf-8"))
+
+    def _serve_health(self) -> None:
+        """Serve health check."""
+        content = '{"status": "ok"}'
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(content)))
+        self.end_headers()
+        self.wfile.write(content.encode("utf-8"))
+
+    def log_message(self, format: str, *args: object) -> None:
+        """Suppress default logging."""
+
+
+class MetricsServer:
+    """HTTP server for exposing metrics to Prometheus.
+
+    Usage:
+        server = MetricsServer(port=8081)
+        server.start()
+        # ... run your application ...
+        server.stop()
+
+    Or as context manager:
+        with MetricsServer(port=8081):
+            # ... run your application ...
+
+    Or as async context manager:
+        async with MetricsServer(port=8081):
+            # ... run your application ...
+    """
+
+    instance: ClassVar["MetricsServer | None"] = None
+
+    def __init__(self, host: str = "0.0.0.0", port: int = 8081) -> None:
+        """Initialize the metrics server.
+
+        Args:
+            host: Host to bind to (default: 0.0.0.0 for all interfaces).
+            port: Port to listen on (default: 8081).
+        """
+        self.host = host
+        self.port = port
+        self._server: HTTPServer | None = None
+        self._thread: Thread | None = None
+
+    def start(self) -> None:
+        """Start the metrics server in a background thread."""
+        if self._server is not None:
+            logger.warning("Metrics server already running")
+            return
+
+        self._server = HTTPServer((self.host, self.port), MetricsHandler)
+        self._thread = Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+        logger.info(
+            "Metrics server started on http://%s:%s/metrics",
+            self.host,
+            self.port,
+        )
+
+    def stop(self) -> None:
+        """Stop the metrics server."""
+        if self._server is not None:
+            self._server.shutdown()
+            self._server = None
+            self._thread = None
+            logger.info("Metrics server stopped")
+
+    async def __aenter__(self) -> "Self":
+        """Async context manager entry."""
+        self.start()
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        """Async context manager exit."""
+        self.stop()
+
+    def __enter__(self) -> "Self":
+        """Context manager entry."""
+        self.start()
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """Context manager exit."""
+        self.stop()
+
+
+def start_metrics_server(host: str = "0.0.0.0", port: int = 8081) -> MetricsServer:
+    """Start a metrics server singleton.
+
+    Args:
+        host: Host to bind to.
+        port: Port to listen on.
+
+    Returns:
+        The MetricsServer instance.
+    """
+    if MetricsServer.instance is None:
+        MetricsServer.instance = MetricsServer(host, port)
+        MetricsServer.instance.start()
+    return MetricsServer.instance
+
+
+def stop_metrics_server() -> None:
+    """Stop the metrics server singleton."""
+    if MetricsServer.instance is not None:
+        MetricsServer.instance.stop()
+        MetricsServer.instance = None