hmdl 0.0.1__tar.gz

hmdl-0.0.1/.gitignore

@@ -0,0 +1,80 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+

hmdl-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hmdl-inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hmdl-0.0.1/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: hmdl
+Version: 0.0.1
+Summary: Observability SDK for MCP (Model Context Protocol) servers - Heimdall Platform
+Project-URL: Homepage, https://tryheimdall.com
+Project-URL: Documentation, https://docs.tryheimdall.com
+Project-URL: Repository, https://github.com/hmdl-inc/heimdall-python
+Project-URL: Issues, https://github.com/hmdl-inc/heimdall-python/issues
+Author-email: Heimdall Team <founder@tryheimdall.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,llm,mcp,model-context-protocol,monitoring,observability,opentelemetry,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Requires-Dist: opentelemetry-semantic-conventions>=0.41b0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hmdl - Heimdall Observability SDK for Python
+
+[![PyPI version](https://badge.fury.io/py/hmdl.svg)](https://badge.fury.io/py/hmdl)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Observability SDK for MCP (Model Context Protocol) servers, built on OpenTelemetry.
+
+## Installation
+
+```bash
+pip install hmdl
+```
+
+## Quick Start
+
+### 1. Create Organization and Project in Heimdall
+
+Before using the SDK, you need to set up your organization and project in the Heimdall dashboard:
+
+1. Start the Heimdall backend and frontend (see [Heimdall Documentation](https://docs.tryheimdall.com))
+2. Navigate to http://localhost:5173
+3. **Create an account** with your email and password
+4. **Create an Organization** - this groups your projects together
+5. **Create a Project** - each project has a unique ID for trace collection
+6. Go to **Settings** to find your **Organization ID** and **Project ID**
+
+### 2. Set up environment variables
+
+```bash
+# Required for local development
+export HEIMDALL_ENDPOINT="http://localhost:4318"  # Your Heimdall backend
+export HEIMDALL_ORG_ID="your-org-id"              # From Heimdall Settings page
+export HEIMDALL_PROJECT_ID="your-project-id"      # From Heimdall Settings page
+export HEIMDALL_ENABLED="true"
+
+# Optional
+export HEIMDALL_SERVICE_NAME="my-mcp-server"
+export HEIMDALL_ENVIRONMENT="development"
+
+# For production (with API key)
+export HEIMDALL_API_KEY="your-api-key"
+export HEIMDALL_ENDPOINT="https://api.heimdall.dev"
+```
+
+### 3. Initialize the client
+
+```python
+from hmdl import HeimdallClient
+
+# Initialize (uses environment variables by default)
+client = HeimdallClient()
+
+# Or with explicit configuration
+client = HeimdallClient(
+    endpoint="http://localhost:4318",
+    org_id="your-org-id",           # From Settings page
+    project_id="your-project-id",   # From Settings page
+    service_name="my-mcp-server",
+    environment="development"
+)
+```
+
+### 4. Instrument your MCP tool functions
+
+```python
+from hmdl import trace_mcp_tool
+
+@trace_mcp_tool()
+def search_documents(query: str, limit: int = 10) -> list:
+    """Search for documents matching the query."""
+    # Your implementation here
+    return results
+
+@trace_mcp_tool("custom-tool-name")
+def another_tool(data: dict) -> dict:
+    """Another MCP tool with custom name."""
+    return {"processed": True, **data}
+```
+
+### 5. Async support
+
+The decorator works with async functions:
+
+```python
+@trace_mcp_tool()
+async def async_search(query: str) -> list:
+    results = await database.search(query)
+    return results
+```
+
+## Configuration
+
+| Environment Variable | Description | Default |
+|---------------------|-------------|---------|
+| `HEIMDALL_ENDPOINT` | Heimdall backend URL | `http://localhost:4318` |
+| `HEIMDALL_ORG_ID` | Organization ID (from Settings page) | `default` |
+| `HEIMDALL_PROJECT_ID` | Project ID (from Settings page) | `default` |
+| `HEIMDALL_ENABLED` | Enable/disable tracing | `true` |
+| `HEIMDALL_SERVICE_NAME` | Service name for traces | `mcp-server` |
+| `HEIMDALL_ENVIRONMENT` | Deployment environment | `development` |
+| `HEIMDALL_API_KEY` | API key (optional for local dev) | - |
+| `HEIMDALL_DEBUG` | Enable debug logging | `false` |
+| `HEIMDALL_BATCH_SIZE` | Spans per batch | `100` |
+| `HEIMDALL_FLUSH_INTERVAL_MS` | Flush interval (ms) | `5000` |
+
+### Local Development
+
+For local development, you don't need an API key. Just set:
+
+```bash
+export HEIMDALL_ENDPOINT="http://localhost:4318"
+export HEIMDALL_ORG_ID="your-org-id"          # Copy from Settings page
+export HEIMDALL_PROJECT_ID="your-project-id"  # Copy from Settings page
+export HEIMDALL_ENABLED="true"
+```
+
+## Advanced Usage
+
+### Custom span names
+
+```python
+@trace_mcp_tool("custom-tool-name")
+def my_tool():
+    pass
+```
+
+### Manual spans
+
+```python
+from hmdl import HeimdallClient
+
+client = HeimdallClient()
+
+with client.start_span("my-operation") as span:
+    span.set_attribute("custom.attribute", "value")
+    # Your code here
+```
+
+### Flush on shutdown
+
+```python
+import atexit
+from hmdl import HeimdallClient
+
+client = HeimdallClient()
+
+# Ensure spans are flushed on exit
+atexit.register(client.flush)
+```
+
+## What gets tracked?
+
+For each MCP function call, Heimdall tracks:
+
+- **Input parameters**: Function arguments (serialized to JSON)
+- **Output/response**: Return value (serialized to JSON)
+- **Status**: Success or error
+- **Latency**: Execution time in milliseconds
+- **Errors**: Exception type, message, and stack trace
+- **Metadata**: Service name, environment, timestamps
+
+## OpenTelemetry Integration
+
+This SDK is built on OpenTelemetry, making it compatible with the broader observability ecosystem. You can:
+
+- Use existing OTel instrumentations alongside Heimdall
+- Export to multiple backends simultaneously
+- Leverage OTel's context propagation for distributed tracing
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+

hmdl-0.0.1/README.md

@@ -0,0 +1,174 @@
+# hmdl - Heimdall Observability SDK for Python
+
+[![PyPI version](https://badge.fury.io/py/hmdl.svg)](https://badge.fury.io/py/hmdl)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Observability SDK for MCP (Model Context Protocol) servers, built on OpenTelemetry.
+
+## Installation
+
+```bash
+pip install hmdl
+```
+
+## Quick Start
+
+### 1. Create Organization and Project in Heimdall
+
+Before using the SDK, you need to set up your organization and project in the Heimdall dashboard:
+
+1. Start the Heimdall backend and frontend (see [Heimdall Documentation](https://docs.tryheimdall.com))
+2. Navigate to http://localhost:5173
+3. **Create an account** with your email and password
+4. **Create an Organization** - this groups your projects together
+5. **Create a Project** - each project has a unique ID for trace collection
+6. Go to **Settings** to find your **Organization ID** and **Project ID**
+
+### 2. Set up environment variables
+
+```bash
+# Required for local development
+export HEIMDALL_ENDPOINT="http://localhost:4318"  # Your Heimdall backend
+export HEIMDALL_ORG_ID="your-org-id"              # From Heimdall Settings page
+export HEIMDALL_PROJECT_ID="your-project-id"      # From Heimdall Settings page
+export HEIMDALL_ENABLED="true"
+
+# Optional
+export HEIMDALL_SERVICE_NAME="my-mcp-server"
+export HEIMDALL_ENVIRONMENT="development"
+
+# For production (with API key)
+export HEIMDALL_API_KEY="your-api-key"
+export HEIMDALL_ENDPOINT="https://api.heimdall.dev"
+```
+
+### 3. Initialize the client
+
+```python
+from hmdl import HeimdallClient
+
+# Initialize (uses environment variables by default)
+client = HeimdallClient()
+
+# Or with explicit configuration
+client = HeimdallClient(
+    endpoint="http://localhost:4318",
+    org_id="your-org-id",           # From Settings page
+    project_id="your-project-id",   # From Settings page
+    service_name="my-mcp-server",
+    environment="development"
+)
+```
+
+### 4. Instrument your MCP tool functions
+
+```python
+from hmdl import trace_mcp_tool
+
+@trace_mcp_tool()
+def search_documents(query: str, limit: int = 10) -> list:
+    """Search for documents matching the query."""
+    # Your implementation here
+    return results
+
+@trace_mcp_tool("custom-tool-name")
+def another_tool(data: dict) -> dict:
+    """Another MCP tool with custom name."""
+    return {"processed": True, **data}
+```
+
+### 5. Async support
+
+The decorator works with async functions:
+
+```python
+@trace_mcp_tool()
+async def async_search(query: str) -> list:
+    results = await database.search(query)
+    return results
+```
+
+## Configuration
+
+| Environment Variable | Description | Default |
+|---------------------|-------------|---------|
+| `HEIMDALL_ENDPOINT` | Heimdall backend URL | `http://localhost:4318` |
+| `HEIMDALL_ORG_ID` | Organization ID (from Settings page) | `default` |
+| `HEIMDALL_PROJECT_ID` | Project ID (from Settings page) | `default` |
+| `HEIMDALL_ENABLED` | Enable/disable tracing | `true` |
+| `HEIMDALL_SERVICE_NAME` | Service name for traces | `mcp-server` |
+| `HEIMDALL_ENVIRONMENT` | Deployment environment | `development` |
+| `HEIMDALL_API_KEY` | API key (optional for local dev) | - |
+| `HEIMDALL_DEBUG` | Enable debug logging | `false` |
+| `HEIMDALL_BATCH_SIZE` | Spans per batch | `100` |
+| `HEIMDALL_FLUSH_INTERVAL_MS` | Flush interval (ms) | `5000` |
+
+### Local Development
+
+For local development, you don't need an API key. Just set:
+
+```bash
+export HEIMDALL_ENDPOINT="http://localhost:4318"
+export HEIMDALL_ORG_ID="your-org-id"          # Copy from Settings page
+export HEIMDALL_PROJECT_ID="your-project-id"  # Copy from Settings page
+export HEIMDALL_ENABLED="true"
+```
+
+## Advanced Usage
+
+### Custom span names
+
+```python
+@trace_mcp_tool("custom-tool-name")
+def my_tool():
+    pass
+```
+
+### Manual spans
+
+```python
+from hmdl import HeimdallClient
+
+client = HeimdallClient()
+
+with client.start_span("my-operation") as span:
+    span.set_attribute("custom.attribute", "value")
+    # Your code here
+```
+
+### Flush on shutdown
+
+```python
+import atexit
+from hmdl import HeimdallClient
+
+client = HeimdallClient()
+
+# Ensure spans are flushed on exit
+atexit.register(client.flush)
+```
+
+## What gets tracked?
+
+For each MCP function call, Heimdall tracks:
+
+- **Input parameters**: Function arguments (serialized to JSON)
+- **Output/response**: Return value (serialized to JSON)
+- **Status**: Success or error
+- **Latency**: Execution time in milliseconds
+- **Errors**: Exception type, message, and stack trace
+- **Metadata**: Service name, environment, timestamps
+
+## OpenTelemetry Integration
+
+This SDK is built on OpenTelemetry, making it compatible with the broader observability ecosystem. You can:
+
+- Use existing OTel instrumentations alongside Heimdall
+- Export to multiple backends simultaneously
+- Leverage OTel's context propagation for distributed tracing
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+

hmdl-0.0.1/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hmdl"
+version = "0.0.1"
+description = "Observability SDK for MCP (Model Context Protocol) servers - Heimdall Platform"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Heimdall Team", email = "founder@tryheimdall.com" }
+]
+keywords = [
+    "observability",
+    "mcp",
+    "model-context-protocol",
+    "opentelemetry",
+    "tracing",
+    "monitoring",
+    "llm",
+    "ai"
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "opentelemetry-api>=1.20.0",
+    "opentelemetry-sdk>=1.20.0",
+    "opentelemetry-exporter-otlp>=1.20.0",
+    "opentelemetry-semantic-conventions>=0.41b0",
+    "typing-extensions>=4.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+    "mypy>=1.0.0",
+    "ruff>=0.1.0",
+    "black>=23.0.0",
+]
+
+[project.urls]
+Homepage = "https://tryheimdall.com"
+Documentation = "https://docs.tryheimdall.com"
+Repository = "https://github.com/hmdl-inc/heimdall-python"
+Issues = "https://github.com/hmdl-inc/heimdall-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hmdl"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+

hmdl-0.0.1/src/hmdl/__init__.py

@@ -0,0 +1,28 @@
+"""
+Heimdall Observability SDK for MCP Servers.
+
+A Python SDK for instrumenting MCP (Model Context Protocol) servers with
+OpenTelemetry-based observability tracking.
+"""
+
+from hmdl.client import HeimdallClient
+from hmdl.decorators import trace_mcp_tool
+from hmdl.config import HeimdallConfig
+from hmdl.types import SpanKind, SpanStatus
+
+__version__ = "0.0.1"
+
+__all__ = [
+    # Client
+    "HeimdallClient",
+    # Decorators
+    "trace_mcp_tool",
+    # Configuration
+    "HeimdallConfig",
+    # Types
+    "SpanKind",
+    "SpanStatus",
+    # Version
+    "__version__",
+]
+

hmdl-0.0.1/src/hmdl/client.py

@@ -0,0 +1,196 @@
+"""Heimdall client for OpenTelemetry-based observability."""
+
+from __future__ import annotations
+
+import atexit
+import logging
+from typing import Optional, Dict, Any
+
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.sdk.resources import Resource, SERVICE_NAME
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+
+from hmdl.config import HeimdallConfig
+from hmdl.types import HeimdallAttributes
+
+logger = logging.getLogger(__name__)
+
+
+class HeimdallClient:
+    """Client for sending observability data to Heimdall platform.
+    
+    This client sets up OpenTelemetry tracing and provides methods for
+    creating spans and recording MCP operations.
+    
+    Example:
+        >>> from hmdl import HeimdallClient
+        >>> client = HeimdallClient(api_key="your-api-key")
+        >>> with client.start_span("my-operation") as span:
+        ...     # Your code here
+        ...     span.set_attribute("custom.attribute", "value")
+    """
+    
+    _instance: Optional["HeimdallClient"] = None
+    _initialized: bool = False
+    
+    def __new__(cls, *args: Any, **kwargs: Any) -> "HeimdallClient":
+        """Singleton pattern to ensure only one client instance."""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+    
+    def __init__(
+        self,
+        config: Optional[HeimdallConfig] = None,
+        api_key: Optional[str] = None,
+        endpoint: Optional[str] = None,
+        service_name: Optional[str] = None,
+        environment: Optional[str] = None,
+        org_id: Optional[str] = None,
+        project_id: Optional[str] = None,
+    ) -> None:
+        """Initialize the Heimdall client.
+
+        Args:
+            config: Full configuration object. If provided, other args are ignored.
+            api_key: API key for Heimdall platform.
+            endpoint: Heimdall platform endpoint URL.
+            service_name: Name of the service being instrumented.
+            environment: Deployment environment.
+            org_id: Organization ID from Heimdall dashboard.
+            project_id: Project ID from Heimdall dashboard.
+        """
+        if self._initialized:
+            return
+
+        # Build config from arguments or use provided config
+        if config is not None:
+            self.config = config
+        else:
+            self.config = HeimdallConfig(
+                api_key=api_key or HeimdallConfig().api_key,
+                endpoint=endpoint or HeimdallConfig().endpoint,
+                service_name=service_name or HeimdallConfig().service_name,
+                environment=environment or HeimdallConfig().environment,
+                org_id=org_id or HeimdallConfig().org_id,
+                project_id=project_id or HeimdallConfig().project_id,
+            )
+        
+        self._tracer: Optional[trace.Tracer] = None
+        self._provider: Optional[TracerProvider] = None
+        
+        if self.config.enabled:
+            self._setup_tracing()
+        
+        self._initialized = True
+        
+        # Register cleanup on exit
+        atexit.register(self.shutdown)
+    
+    def _setup_tracing(self) -> None:
+        """Set up OpenTelemetry tracing."""
+        if self.config.debug:
+            logging.basicConfig(level=logging.DEBUG)
+            logger.setLevel(logging.DEBUG)
+        
+        # Create resource with service information
+        resource = Resource.create({
+            SERVICE_NAME: self.config.service_name,
+            HeimdallAttributes.HEIMDALL_ENVIRONMENT: self.config.environment,
+            HeimdallAttributes.HEIMDALL_ORG_ID: self.config.org_id,
+            HeimdallAttributes.HEIMDALL_PROJECT_ID: self.config.project_id,
+        })
+        
+        # Create tracer provider
+        self._provider = TracerProvider(resource=resource)
+        
+        # Set up OTLP HTTP exporter
+        otlp_endpoint = f"{self.config.endpoint}/v1/traces"
+
+        # Only add auth header if API key is provided
+        headers = {}
+        if self.config.api_key:
+            headers["Authorization"] = f"Bearer {self.config.api_key}"
+
+        exporter = OTLPSpanExporter(
+            endpoint=otlp_endpoint,
+            headers=headers if headers else None,
+        )
+        
+        # Add batch processor for efficient span export
+        processor = BatchSpanProcessor(
+            exporter,
+            max_queue_size=self.config.max_queue_size,
+            max_export_batch_size=self.config.batch_size,
+            schedule_delay_millis=self.config.flush_interval_ms,
+        )
+        self._provider.add_span_processor(processor)
+        
+        # Set as global tracer provider
+        trace.set_tracer_provider(self._provider)
+        
+        # Get tracer
+        self._tracer = trace.get_tracer("hmdl", "0.1.0")
+        
+        logger.debug(f"Heimdall tracing initialized for service: {self.config.service_name}")
+
+    @property
+    def tracer(self) -> trace.Tracer:
+        """Get the OpenTelemetry tracer."""
+        if self._tracer is None:
+            # Return a no-op tracer if not initialized
+            return trace.get_tracer("hmdl-noop")
+        return self._tracer
+
+    def start_span(
+        self,
+        name: str,
+        kind: trace.SpanKind = trace.SpanKind.INTERNAL,
+        attributes: Optional[Dict[str, Any]] = None,
+    ) -> trace.Span:
+        """Start a new span.
+
+        Args:
+            name: Name of the span.
+            kind: Kind of span (INTERNAL, CLIENT, SERVER, etc.).
+            attributes: Initial attributes for the span.
+
+        Returns:
+            The created span as a context manager.
+        """
+        return self.tracer.start_as_current_span(
+            name=name,
+            kind=kind,
+            attributes=attributes,
+        )
+
+    def get_current_span(self) -> trace.Span:
+        """Get the current active span."""
+        return trace.get_current_span()
+
+    def flush(self) -> None:
+        """Flush all pending spans."""
+        if self._provider is not None:
+            self._provider.force_flush()
+
+    def shutdown(self) -> None:
+        """Shutdown the client and flush remaining spans."""
+        if self._provider is not None:
+            self._provider.shutdown()
+            logger.debug("Heimdall client shutdown complete")
+
+    @classmethod
+    def get_instance(cls) -> Optional["HeimdallClient"]:
+        """Get the singleton client instance."""
+        return cls._instance
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset the singleton instance (mainly for testing)."""
+        if cls._instance is not None:
+            cls._instance.shutdown()
+        cls._instance = None
+        cls._initialized = False
+

hmdl-0.0.1/src/hmdl/config.py

@@ -0,0 +1,80 @@
+"""Configuration for Heimdall SDK."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any
+
+
+@dataclass
+class HeimdallConfig:
+    """Configuration for the Heimdall observability client.
+
+    Attributes:
+        api_key: API key for authenticating with Heimdall platform.
+        endpoint: The Heimdall platform endpoint URL.
+        service_name: Name of the service being instrumented.
+        environment: Deployment environment (e.g., 'production', 'staging').
+        org_id: Organization ID from Heimdall dashboard.
+        project_id: Project ID to associate traces with in Heimdall.
+        enabled: Whether tracing is enabled.
+        debug: Enable debug logging.
+        batch_size: Number of spans to batch before sending.
+        flush_interval_ms: Interval in milliseconds to flush spans.
+        max_queue_size: Maximum number of spans to queue.
+        metadata: Additional metadata to attach to all spans.
+    """
+
+    api_key: Optional[str] = field(
+        default_factory=lambda: os.environ.get("HEIMDALL_API_KEY")
+    )
+    endpoint: str = field(
+        default_factory=lambda: os.environ.get(
+            "HEIMDALL_ENDPOINT", "https://api.heimdall.dev"
+        )
+    )
+    service_name: str = field(
+        default_factory=lambda: os.environ.get("HEIMDALL_SERVICE_NAME", "mcp-server")
+    )
+    environment: str = field(
+        default_factory=lambda: os.environ.get("HEIMDALL_ENVIRONMENT", "development")
+    )
+    org_id: str = field(
+        default_factory=lambda: os.environ.get("HEIMDALL_ORG_ID", "default")
+    )
+    project_id: str = field(
+        default_factory=lambda: os.environ.get("HEIMDALL_PROJECT_ID", "default")
+    )
+    enabled: bool = field(
+        default_factory=lambda: os.environ.get("HEIMDALL_ENABLED", "true").lower() == "true"
+    )
+    debug: bool = field(
+        default_factory=lambda: os.environ.get("HEIMDALL_DEBUG", "false").lower() == "true"
+    )
+    batch_size: int = field(
+        default_factory=lambda: int(os.environ.get("HEIMDALL_BATCH_SIZE", "100"))
+    )
+    flush_interval_ms: int = field(
+        default_factory=lambda: int(os.environ.get("HEIMDALL_FLUSH_INTERVAL_MS", "5000"))
+    )
+    max_queue_size: int = field(
+        default_factory=lambda: int(os.environ.get("HEIMDALL_MAX_QUEUE_SIZE", "1000"))
+    )
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    def validate(self) -> None:
+        """Validate the configuration."""
+        # API key is optional for local development
+        if self.batch_size < 1:
+            raise ValueError("batch_size must be at least 1")
+        if self.flush_interval_ms < 100:
+            raise ValueError("flush_interval_ms must be at least 100")
+        if self.max_queue_size < self.batch_size:
+            raise ValueError("max_queue_size must be at least batch_size")
+    
+    @classmethod
+    def from_env(cls) -> "HeimdallConfig":
+        """Create configuration from environment variables."""
+        return cls()
+

hmdl-0.0.1/src/hmdl/decorators.py

@@ -0,0 +1,317 @@
+"""Decorators for instrumenting MCP functions with Heimdall observability."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import json
+import time
+from typing import Any, Callable, Optional, TypeVar, Union, overload
+
+from opentelemetry import trace
+from opentelemetry.trace import Status, StatusCode
+
+from hmdl.types import HeimdallAttributes, SpanKind, SpanStatus
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _serialize_value(value: Any) -> str:
+    """Safely serialize a value to string for span attributes."""
+    try:
+        return json.dumps(value, default=str)
+    except (TypeError, ValueError):
+        return str(value)
+
+
+def _get_client() -> Any:
+    """Get the Heimdall client instance."""
+    from hmdl.client import HeimdallClient
+    return HeimdallClient.get_instance()
+
+
+def _create_span_decorator(
+    span_kind: SpanKind,
+    name_attr: str,
+    args_attr: str,
+    result_attr: str,
+) -> Callable[[Optional[str]], Callable[[F], F]]:
+    """Factory for creating MCP-specific decorators."""
+    
+    def decorator(name: Optional[str] = None) -> Callable[[F], F]:
+        def wrapper(func: F) -> F:
+            span_name = name or func.__name__
+            is_async = inspect.iscoroutinefunction(func)
+            
+            if is_async:
+                @functools.wraps(func)
+                async def async_wrapped(*args: Any, **kwargs: Any) -> Any:
+                    client = _get_client()
+                    if client is None:
+                        return await func(*args, **kwargs)
+                    
+                    tracer = client.tracer
+                    with tracer.start_as_current_span(
+                        name=span_name,
+                        kind=trace.SpanKind.SERVER,
+                    ) as span:
+                        start_time = time.perf_counter()
+                        
+                        # Set input attributes
+                        span.set_attribute(name_attr, span_name)
+                        span.set_attribute("heimdall.span_kind", span_kind.value)
+                        
+                        # Capture arguments
+                        try:
+                            all_args = _capture_arguments(func, args, kwargs)
+                            span.set_attribute(args_attr, _serialize_value(all_args))
+                        except Exception:
+                            pass
+                        
+                        try:
+                            result = await func(*args, **kwargs)
+                            
+                            # Set output attributes
+                            span.set_attribute(result_attr, _serialize_value(result))
+                            span.set_attribute(HeimdallAttributes.STATUS, SpanStatus.OK.value)
+                            span.set_status(Status(StatusCode.OK))
+                            
+                            return result
+                        except Exception as e:
+                            _record_error(span, e)
+                            raise
+                        finally:
+                            duration_ms = (time.perf_counter() - start_time) * 1000
+                            span.set_attribute(HeimdallAttributes.DURATION_MS, duration_ms)
+                
+                return async_wrapped  # type: ignore
+            else:
+                @functools.wraps(func)
+                def sync_wrapped(*args: Any, **kwargs: Any) -> Any:
+                    client = _get_client()
+                    if client is None:
+                        return func(*args, **kwargs)
+                    
+                    tracer = client.tracer
+                    with tracer.start_as_current_span(
+                        name=span_name,
+                        kind=trace.SpanKind.SERVER,
+                    ) as span:
+                        start_time = time.perf_counter()
+                        
+                        # Set input attributes
+                        span.set_attribute(name_attr, span_name)
+                        span.set_attribute("heimdall.span_kind", span_kind.value)
+                        
+                        # Capture arguments
+                        try:
+                            all_args = _capture_arguments(func, args, kwargs)
+                            span.set_attribute(args_attr, _serialize_value(all_args))
+                        except Exception:
+                            pass
+                        
+                        try:
+                            result = func(*args, **kwargs)
+                            
+                            # Set output attributes
+                            span.set_attribute(result_attr, _serialize_value(result))
+                            span.set_attribute(HeimdallAttributes.STATUS, SpanStatus.OK.value)
+                            span.set_status(Status(StatusCode.OK))
+                            
+                            return result
+                        except Exception as e:
+                            _record_error(span, e)
+                            raise
+                        finally:
+                            duration_ms = (time.perf_counter() - start_time) * 1000
+                            span.set_attribute(HeimdallAttributes.DURATION_MS, duration_ms)
+                
+                return sync_wrapped  # type: ignore
+        
+        return wrapper
+    
+    return decorator
+
+
+def _capture_arguments(func: Callable[..., Any], args: tuple, kwargs: dict) -> dict:
+    """Capture function arguments as a dictionary."""
+    sig = inspect.signature(func)
+    bound = sig.bind_partial(*args, **kwargs)
+    bound.apply_defaults()
+    return dict(bound.arguments)
+
+
+def _record_error(span: trace.Span, error: Exception) -> None:
+    """Record an error on a span."""
+    span.set_attribute(HeimdallAttributes.STATUS, SpanStatus.ERROR.value)
+    span.set_attribute(HeimdallAttributes.ERROR_MESSAGE, str(error))
+    span.set_attribute(HeimdallAttributes.ERROR_TYPE, type(error).__name__)
+    span.set_status(Status(StatusCode.ERROR, str(error)))
+    span.record_exception(error)
+
+
+# Create MCP-specific decorators
+trace_mcp_tool = _create_span_decorator(
+    span_kind=SpanKind.MCP_TOOL,
+    name_attr=HeimdallAttributes.MCP_TOOL_NAME,
+    args_attr=HeimdallAttributes.MCP_TOOL_ARGUMENTS,
+    result_attr=HeimdallAttributes.MCP_TOOL_RESULT,
+)
+trace_mcp_tool.__doc__ = """
+Decorator to trace MCP tool calls.
+
+Example:
+    >>> @trace_mcp_tool()
+    ... def my_tool(arg1: str, arg2: int) -> str:
+    ...     return f"Result: {arg1}, {arg2}"
+
+    >>> @trace_mcp_tool("custom-tool-name")
+    ... async def async_tool(data: dict) -> dict:
+    ...     return {"processed": data}
+"""
+
+trace_mcp_resource = _create_span_decorator(
+    span_kind=SpanKind.MCP_RESOURCE,
+    name_attr=HeimdallAttributes.MCP_RESOURCE_URI,
+    args_attr="mcp.resource.arguments",
+    result_attr="mcp.resource.result",
+)
+trace_mcp_resource.__doc__ = """
+Decorator to trace MCP resource access.
+
+Example:
+    >>> @trace_mcp_resource()
+    ... def read_file(uri: str) -> str:
+    ...     return open(uri).read()
+"""
+
+trace_mcp_prompt = _create_span_decorator(
+    span_kind=SpanKind.MCP_PROMPT,
+    name_attr=HeimdallAttributes.MCP_PROMPT_NAME,
+    args_attr=HeimdallAttributes.MCP_PROMPT_ARGUMENTS,
+    result_attr=HeimdallAttributes.MCP_PROMPT_MESSAGES,
+)
+trace_mcp_prompt.__doc__ = """
+Decorator to trace MCP prompt calls.
+
+Example:
+    >>> @trace_mcp_prompt()
+    ... def generate_prompt(context: str) -> list:
+    ...     return [{"role": "user", "content": context}]
+"""
+
+
+@overload
+def observe(func: F) -> F: ...
+
+@overload
+def observe(
+    name: Optional[str] = None,
+    *,
+    capture_input: bool = True,
+    capture_output: bool = True,
+) -> Callable[[F], F]: ...
+
+def observe(
+    func: Optional[F] = None,
+    name: Optional[str] = None,
+    *,
+    capture_input: bool = True,
+    capture_output: bool = True,
+) -> Union[F, Callable[[F], F]]:
+    """
+    General-purpose decorator to observe any function.
+
+    Can be used with or without arguments:
+
+    Example:
+        >>> @observe
+        ... def my_function():
+        ...     pass
+
+        >>> @observe(name="custom-name", capture_output=False)
+        ... def another_function():
+        ...     pass
+    """
+    def decorator(fn: F) -> F:
+        span_name = name or fn.__name__
+        is_async = inspect.iscoroutinefunction(fn)
+
+        if is_async:
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                client = _get_client()
+                if client is None:
+                    return await fn(*args, **kwargs)
+
+                tracer = client.tracer
+                with tracer.start_as_current_span(
+                    name=span_name,
+                    kind=trace.SpanKind.INTERNAL,
+                ) as span:
+                    start_time = time.perf_counter()
+                    span.set_attribute("heimdall.span_kind", SpanKind.INTERNAL.value)
+
+                    if capture_input:
+                        try:
+                            all_args = _capture_arguments(fn, args, kwargs)
+                            span.set_attribute("heimdall.input", _serialize_value(all_args))
+                        except Exception:
+                            pass
+
+                    try:
+                        result = await fn(*args, **kwargs)
+                        if capture_output:
+                            span.set_attribute("heimdall.output", _serialize_value(result))
+                        span.set_status(Status(StatusCode.OK))
+                        return result
+                    except Exception as e:
+                        _record_error(span, e)
+                        raise
+                    finally:
+                        duration_ms = (time.perf_counter() - start_time) * 1000
+                        span.set_attribute(HeimdallAttributes.DURATION_MS, duration_ms)
+
+            return async_wrapper  # type: ignore
+        else:
+            @functools.wraps(fn)
+            def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+                client = _get_client()
+                if client is None:
+                    return fn(*args, **kwargs)
+
+                tracer = client.tracer
+                with tracer.start_as_current_span(
+                    name=span_name,
+                    kind=trace.SpanKind.INTERNAL,
+                ) as span:
+                    start_time = time.perf_counter()
+                    span.set_attribute("heimdall.span_kind", SpanKind.INTERNAL.value)
+
+                    if capture_input:
+                        try:
+                            all_args = _capture_arguments(fn, args, kwargs)
+                            span.set_attribute("heimdall.input", _serialize_value(all_args))
+                        except Exception:
+                            pass
+
+                    try:
+                        result = fn(*args, **kwargs)
+                        if capture_output:
+                            span.set_attribute("heimdall.output", _serialize_value(result))
+                        span.set_status(Status(StatusCode.OK))
+                        return result
+                    except Exception as e:
+                        _record_error(span, e)
+                        raise
+                    finally:
+                        duration_ms = (time.perf_counter() - start_time) * 1000
+                        span.set_attribute(HeimdallAttributes.DURATION_MS, duration_ms)
+
+            return sync_wrapper  # type: ignore
+
+    # Handle both @observe and @observe() syntax
+    if func is not None:
+        return decorator(func)
+    return decorator
+

hmdl-0.0.1/src/hmdl/py.typed

@@ -0,0 +1 @@
+

hmdl-0.0.1/src/hmdl/types.py

@@ -0,0 +1,114 @@
+"""Type definitions for Heimdall SDK."""
+
+from __future__ import annotations
+
+from enum import Enum
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional, List
+from datetime import datetime
+
+
+class SpanKind(str, Enum):
+    """Kind of span being recorded."""
+    
+    MCP_TOOL = "mcp.tool"
+    MCP_RESOURCE = "mcp.resource"
+    MCP_PROMPT = "mcp.prompt"
+    MCP_REQUEST = "mcp.request"
+    INTERNAL = "internal"
+    CLIENT = "client"
+    SERVER = "server"
+
+
+class SpanStatus(str, Enum):
+    """Status of a span."""
+    
+    UNSET = "unset"
+    OK = "ok"
+    ERROR = "error"
+
+
+@dataclass
+class MCPToolCall:
+    """Represents an MCP tool call."""
+    
+    name: str
+    arguments: Dict[str, Any] = field(default_factory=dict)
+    result: Optional[Any] = None
+    error: Optional[str] = None
+    duration_ms: Optional[float] = None
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+
+
+@dataclass
+class MCPResourceAccess:
+    """Represents an MCP resource access."""
+    
+    uri: str
+    method: str = "read"
+    content_type: Optional[str] = None
+    content_length: Optional[int] = None
+    error: Optional[str] = None
+    duration_ms: Optional[float] = None
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+
+
+@dataclass
+class MCPPromptCall:
+    """Represents an MCP prompt call."""
+    
+    name: str
+    arguments: Dict[str, Any] = field(default_factory=dict)
+    messages: List[Dict[str, Any]] = field(default_factory=list)
+    error: Optional[str] = None
+    duration_ms: Optional[float] = None
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+
+
+@dataclass
+class TraceContext:
+    """Context for a trace."""
+    
+    trace_id: str
+    span_id: str
+    parent_span_id: Optional[str] = None
+    session_id: Optional[str] = None
+    user_id: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    tags: List[str] = field(default_factory=list)
+
+
+# Attribute keys for OpenTelemetry spans
+class HeimdallAttributes:
+    """Standard attribute keys for Heimdall spans."""
+    
+    # MCP specific attributes
+    MCP_TOOL_NAME = "mcp.tool.name"
+    MCP_TOOL_ARGUMENTS = "mcp.tool.arguments"
+    MCP_TOOL_RESULT = "mcp.tool.result"
+    
+    MCP_RESOURCE_URI = "mcp.resource.uri"
+    MCP_RESOURCE_METHOD = "mcp.resource.method"
+    MCP_RESOURCE_CONTENT_TYPE = "mcp.resource.content_type"
+    MCP_RESOURCE_CONTENT_LENGTH = "mcp.resource.content_length"
+    
+    MCP_PROMPT_NAME = "mcp.prompt.name"
+    MCP_PROMPT_ARGUMENTS = "mcp.prompt.arguments"
+    MCP_PROMPT_MESSAGES = "mcp.prompt.messages"
+    
+    # Heimdall specific attributes
+    HEIMDALL_SESSION_ID = "heimdall.session_id"
+    HEIMDALL_USER_ID = "heimdall.user_id"
+    HEIMDALL_ENVIRONMENT = "heimdall.environment"
+    HEIMDALL_SERVICE_NAME = "heimdall.service_name"
+    HEIMDALL_ORG_ID = "heimdall.org_id"
+    HEIMDALL_PROJECT_ID = "heimdall.project_id"
+    
+    # Status and error attributes
+    STATUS = "heimdall.status"
+    ERROR_MESSAGE = "heimdall.error.message"
+    ERROR_TYPE = "heimdall.error.type"
+    
+    # Timing attributes
+    DURATION_MS = "heimdall.duration_ms"
+