turingpulse-sdk 1.0.0__tar.gz

turingpulse_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: turingpulse-sdk
+Version: 1.0.0
+Summary: Python plugin decorators for TuringPulse observability, governance, and KPI mapping.
+Author: TuringPulse
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3.0.0,>=2.7.0
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: opentelemetry-api<2.0.0,>=1.21.0
+Requires-Dist: typing_extensions>=4.9.0
+Requires-Dist: turingpulse-interfaces>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2.0; extra == "dev"
+Requires-Dist: anyio>=4.3.0; extra == "dev"

turingpulse_sdk-1.0.0/README.md

@@ -0,0 +1,215 @@
+# TuringPulse Python SDK
+
+End-to-end instrumentation helpers that let any Python service publish telemetry to the Agent Observability Service, open governance tasks in the Agent PM Service, and register agent entrypoints without touching the host application's core configuration.
+
+## Framework Compatibility
+
+<!-- COMPAT-BADGES:START -->
+![AWS Bedrock](https://img.shields.io/badge/AWS%20Bedrock-passing-brightgreen) ![Mistral](https://img.shields.io/badge/Mistral-passing-brightgreen)
+<!-- COMPAT-BADGES:END -->
+
+<details>
+<summary>Full Compatibility Matrix</summary>
+
+<!-- COMPAT-MATRIX:START -->
+| Framework | Version | Python 3.11 | Python 3.12 | Python 3.13 |
+|---|---| ---| ---| --- |
+| AWS Bedrock | 1.42.66 | -- | -- | pass |
+| Mistral | 0.4.0 | pass | -- | -- |
+| Mistral | 2.0.1 | -- | pass | -- |
+<!-- COMPAT-MATRIX:END -->
+
+</details>
+
+## Highlights
+
+- `TuringPulsePlugin.init(...)` bootstraps connectivity (base URLs, tenant headers, API keys, tracing defaults).
+- `@turingpulse.instrument(...)` decorator captures latency, status, errors, KPI mappings, and governance directives (HITL/HATL/HOTL) for both sync and async functions.
+- Automatic OpenTelemetry span management with optional custom labels and KPI-derived attributes.
+- Governance helper automatically creates PM tasks and HITL actions with reviewer/escalation metadata.
+- Trigger registry lets you invoke decorated agent entrypoints that are not exposed via HTTP/UI endpoints.
+
+## Quickstart
+
+```bash
+pip install -e packages/interfaces-py          # shared models
+pip install -e packages/turingpulse-sdk
+```
+
+```python
+from turingpulse_sdk import TuringPulseConfig, init, instrument, GovernanceDirective, KPIConfig
+
+# Minimal setup — only API key and workflow name (URLs and tenant/project resolved automatically)
+init(
+    TuringPulseConfig(
+        api_key="sk_...",
+        workflow_name="My Workflow",
+        use_ingestion_service=True,
+    )
+)
+
+# Or with explicit URLs/tenant (e.g. self-hosted or overrides)
+init(
+    TuringPulseConfig(
+        api_key="sk_...",
+        workflow_name="My Workflow",
+        pm_url="http://localhost:8002",
+        ingestion_url="http://localhost:8004",
+        use_ingestion_service=True,
+    )
+)
+
+
+@instrument(
+    agent_id="agent-research",
+    operation="market_scan",
+    labels={"surface": "slack"},
+    governance=GovernanceDirective(hitl=True, reviewers=["audit@org.com"]),
+    kpis=[
+        KPIConfig(kpi_id="latency_ms", use_duration=True, alert_threshold=8000, comparator="gt"),
+    ],
+    trigger_key="hidden.market_scan",
+)
+def run_market_scan(query: str) -> dict:
+    ...
+```
+
+## Decorator Options
+
+| Option | Description |
+| --- | --- |
+| `agent_id` | Required Agent identifier used by observability + governance |
+| `operation` | Logical operation name; defaults to function __name__ |
+| `labels` | Dict merged with global defaults and exposed to traces/custom metrics |
+| `trace` | Enable/disable tracing per function |
+| `trigger_key` | Registers callable for manual triggering via `TuringPulsePlugin.trigger_agent` |
+| `governance` | `GovernanceDirective` describing HITL/HATL/HOTL expectations |
+| `kpis` | List of `KPIConfig` definitions to emit custom metrics + alerts |
+| `trigger_hidden_agent` | When True, plugin calls the agent even if it's hidden from UI |
+
+## Manual Triggers
+
+```python
+from turingpulse_sdk import get_plugin
+
+get_plugin().trigger_agent("hidden.market_scan", query="pricing updates")
+```
+
+## KPI & Alerting
+
+- KPIs can derive values from runtime context via callables (`lambda ctx: len(ctx.result["items"])`).
+- When `alert_threshold` is crossed, the plugin attaches `metric.alert=true` metadata so the observability service can raise KPI alerts downstream.
+
+## Governance
+
+`GovernanceDirective` supports HITL (human-in-the-loop), HATL (human-after-the-loop), and HOTL (human-on-the-loop) patterns. The directive controls:
+
+- which reviewer queues/tasks to open in the PM service,
+- escalation channels & metadata,
+- auto-escalation timers,
+- whether the invocation should block on HITL.
+
+## Security
+
+The SDK includes built-in protections to ensure safe operation in customer environments:
+
+### Endpoint Validation
+- **SSRF protection**: Private/internal IP ranges (`127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.0.0/16`, `localhost`, `[::1]`) are blocked as endpoints.
+- **CRLF injection prevention**: Newline and null characters are stripped from API keys and endpoint URLs.
+- **TLS enforcement**: The SDK emits a warning if an `http://` endpoint is used instead of `https://`.
+
+### Data Protection
+- **Sensitive field redaction**: Use `redact_fields` in `TuringPulseConfig` to mask sensitive keys before telemetry leaves your environment.
+- **Error sanitization**: Error messages in telemetry do not include stack traces or internal paths.
+- **No content truncation**: The SDK does not truncate or limit content size — backend handles that.
+
+```python
+init(TuringPulseConfig(
+    api_key="sk_...",
+    workflow_name="My Workflow",
+    redact_fields=["password", "api_key", "secret", "token", "authorization"],
+))
+```
+
+### File Attachments
+- **Path traversal prevention**: `attach_document()` normalises file paths and rejects symlinks, device files, and directory traversal patterns.
+- **Filename sanitisation**: Control characters and path components are stripped from filenames.
+
+### Network Safety
+- **Retry-After compliance**: The SDK respects `Retry-After` headers from 429 responses.
+- **No retry on terminal errors**: 401, 402, 403, 404 responses stop retries immediately.
+- **Timeout cap**: HTTP timeout is capped at 120 seconds.
+
+## Fingerprinting & Change Detection
+
+The SDK automatically captures workflow fingerprints to enable root cause analysis when anomalies or drifts are detected. This works out-of-the-box with zero configuration.
+
+### How It Works
+
+1. The SDK automatically detects LLM calls (OpenAI, Anthropic, LangChain, etc.)
+2. Prompts and configurations are hashed for change detection
+3. Workflow structure (nodes and edges) is tracked
+4. Fingerprints are sent to the backend after each run
+5. When anomalies occur, changes are correlated for root cause attribution
+
+### Configuration
+
+```python
+from turingpulse_sdk import init, FingerprintConfig
+
+init(
+    observability_url="http://localhost:8001/v1",
+    tenant_id="tenant-42",
+    fingerprint=FingerprintConfig(
+        enabled=True,              # Master switch (default: True)
+        capture_prompts=True,      # Hash prompts for change detection
+        capture_configs=True,      # Hash configs for change detection
+        capture_structure=True,    # Track DAG structure
+        sensitive_config_keys=[    # Keys to redact before hashing
+            "api_key", "password", "secret", "token"
+        ],
+        send_async=True,           # Send fingerprints asynchronously
+        send_on_failure=True,      # Send even if run fails
+    )
+)
+```
+
+### Deploy Tracking
+
+Register deployments to correlate anomalies with code changes:
+
+```python
+from turingpulse_sdk import register_deploy
+import os
+
+# Auto-detect from CI/CD environment (GitHub Actions, GitLab CI, etc.)
+register_deploy(
+    workflow_id="chat-assistant",
+    auto_detect=True,
+)
+
+# Or provide explicit values
+register_deploy(
+    workflow_id="chat-assistant",
+    version="v1.2.3",
+    git_sha=os.getenv("GIT_SHA"),
+    commit_message=os.getenv("GIT_COMMIT_MSG"),
+)
+```
+
+Supported CI/CD environments for auto-detection:
+- GitHub Actions
+- GitLab CI
+- CircleCI
+- Jenkins
+- Azure DevOps
+- Bitbucket Pipelines
+- Travis CI
+
+## Roadmap
+
+- Typed FastAPI/Flask middleware shims
+- Async batch exporter for very high volume workloads
+- Richer KPI authoring toolkit and alert subscriptions
+
+

turingpulse_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "turingpulse-sdk"
+version = "1.0.0"
+description = "Python plugin decorators for TuringPulse observability, governance, and KPI mapping."
+authors = [{name = "TuringPulse"}]
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2.7.0,<3.0.0",
+    "httpx>=0.26.0",
+    "opentelemetry-api>=1.21.0,<2.0.0",
+    "typing_extensions>=4.9.0",
+    "turingpulse-interfaces>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.2.0", "anyio>=4.3.0"]
+
+[tool.setuptools.packages.find]
+include = ["turingpulse_sdk*"]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"

turingpulse_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

turingpulse_sdk-1.0.0/tests/test_cross_framework_fingerprint.py

@@ -0,0 +1,378 @@
+"""Cross-framework fingerprint categorization tests.
+
+Validates that config keys extracted by every supported LLM provider are
+correctly classified into the right hash categories (model, eval, policy,
+general).  Uses the actual CONFIG_KEYS lists from llm_detector.py to
+ensure there is no drift between what the SDK extracts and what the
+fingerprint builder categorises.
+"""
+
+import pytest
+from turingpulse_sdk.fingerprint import (
+    FingerprintBuilder,
+    FingerprintConfig,
+    classify_config_key,
+    split_config,
+)
+from turingpulse_sdk.llm_detector import PROVIDERS
+
+
+def _provider_keys(name: str) -> list:
+    """Look up config_keys for a provider by name from the PROVIDERS registry."""
+    for spec in PROVIDERS:
+        if spec.name == name:
+            return spec.config_keys
+    raise ValueError(f"Unknown provider: {name}")
+
+
+# ---------------------------------------------------------------------------
+# Provider config key definitions (from PROVIDERS registry in llm_detector)
+# ---------------------------------------------------------------------------
+
+PROVIDER_CONFIGS = {
+    "openai": {
+        "keys": _provider_keys("openai"),
+        "sample": {"model": "gpt-4o", "temperature": 0.7, "max_tokens": 2000,
+                    "top_p": 0.9, "frequency_penalty": 0.1, "presence_penalty": 0.2, "stop": ["\n"]},
+        "expected_model_keys": {"model", "temperature", "max_tokens", "top_p",
+                                "frequency_penalty", "presence_penalty", "stop"},
+        "expected_general_keys": set(),
+    },
+    "anthropic": {
+        "keys": _provider_keys("anthropic"),
+        "sample": {"model": "claude-3-opus", "temperature": 0.5, "max_tokens": 4096,
+                    "top_p": 0.95, "stop_sequences": ["</answer>"]},
+        "expected_model_keys": {"model", "temperature", "max_tokens", "top_p", "stop_sequences"},
+        "expected_general_keys": set(),
+    },
+    "google": {
+        "keys": _provider_keys("google"),
+        "sample": {"model": "gemini-pro", "temperature": 0.8, "max_output_tokens": 1024,
+                    "top_p": 0.9, "top_k": 40},
+        "expected_model_keys": {"model", "temperature", "max_output_tokens", "top_p", "top_k"},
+        "expected_general_keys": set(),
+    },
+    "vertexai": {
+        "keys": _provider_keys("vertexai"),
+        "sample": {"model": "gemini-1.5-pro", "temperature": 0.4, "max_output_tokens": 2048,
+                    "top_p": 0.8, "top_k": 32, "candidate_count": 1},
+        "expected_model_keys": {"model", "temperature", "max_output_tokens", "top_p", "top_k", "candidate_count"},
+        "expected_general_keys": set(),
+    },
+    "langchain": {
+        "keys": _provider_keys("langchain"),
+        "sample": {"model_name": "gpt-4", "temperature": 0.7, "max_tokens": 1000,
+                    "model_kwargs": {"seed": 42}},
+        "expected_model_keys": {"model_name", "temperature", "max_tokens", "model_kwargs"},
+        "expected_general_keys": set(),
+    },
+    "langgraph": {
+        "keys": _provider_keys("langgraph"),
+        "sample": {"model_name": "gpt-4o", "temperature": 0.5, "max_tokens": 1500,
+                    "recursion_limit": 25, "configurable": {"thread_id": "abc"}},
+        "expected_model_keys": {"model_name", "temperature", "max_tokens"},
+        "expected_general_keys": {"recursion_limit", "configurable"},
+    },
+    "crewai": {
+        "keys": _provider_keys("crewai"),
+        "sample": {"model": "gpt-4o", "temperature": 0.3, "max_tokens": 500,
+                    "verbose": True, "memory": True},
+        "expected_model_keys": {"model", "temperature", "max_tokens"},
+        "expected_general_keys": {"verbose", "memory"},
+    },
+    "autogen": {
+        "keys": _provider_keys("autogen"),
+        "sample": {"model": "gpt-4", "temperature": 0.0, "max_tokens": 2000,
+                    "timeout": 120, "cache_seed": 42},
+        "expected_model_keys": {"model", "temperature", "max_tokens"},
+        "expected_general_keys": {"cache_seed"},
+        "expected_policy_keys": {"timeout"},
+    },
+    "llamaindex": {
+        "keys": _provider_keys("llamaindex"),
+        "sample": {"model": "gpt-4", "temperature": 0.1, "max_tokens": 3000,
+                    "context_window": 128000},
+        "expected_model_keys": {"model", "temperature", "max_tokens", "context_window"},
+        "expected_general_keys": set(),
+    },
+    "bedrock": {
+        "keys": _provider_keys("bedrock"),
+        "sample": {"modelId": "anthropic.claude-3-sonnet", "temperature": 0.7,
+                    "maxTokens": 4096, "topP": 0.9, "stopSequences": ["</result>"]},
+        "expected_model_keys": {"modelId", "temperature", "maxTokens", "topP", "stopSequences"},
+        "expected_general_keys": set(),
+    },
+    "cohere": {
+        "keys": _provider_keys("cohere"),
+        "sample": {"model": "command-r-plus", "temperature": 0.3, "max_tokens": 1000,
+                    "p": 0.9, "k": 40},
+        "expected_model_keys": {"model", "temperature", "max_tokens", "p", "k"},
+        "expected_general_keys": set(),
+    },
+    "mistral": {
+        "keys": _provider_keys("mistral"),
+        "sample": {"model": "mistral-large-latest", "temperature": 0.5,
+                    "max_tokens": 2000, "top_p": 0.95},
+        "expected_model_keys": {"model", "temperature", "max_tokens", "top_p"},
+        "expected_general_keys": set(),
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# Per-key classification tests
+# ---------------------------------------------------------------------------
+
+
+class TestPerProviderKeyClassification:
+    """Verify every extracted config key is classified into the correct category."""
+
+    @pytest.mark.parametrize("provider,spec", list(PROVIDER_CONFIGS.items()))
+    def test_all_keys_classified_correctly(self, provider: str, spec: dict):
+        """Every key from a provider should be classified as model or general (not unknown)."""
+        expected_model = spec["expected_model_keys"]
+        expected_general = spec["expected_general_keys"]
+        expected_policy = spec.get("expected_policy_keys", set())
+        expected_eval = spec.get("expected_eval_keys", set())
+
+        for key in spec["keys"]:
+            category = classify_config_key(key)
+            if key in expected_model:
+                assert category == "model", \
+                    f"[{provider}] Key '{key}' expected model, got {category}"
+            elif key in expected_eval:
+                assert category == "eval", \
+                    f"[{provider}] Key '{key}' expected eval, got {category}"
+            elif key in expected_policy:
+                assert category == "policy", \
+                    f"[{provider}] Key '{key}' expected policy, got {category}"
+            elif key in expected_general:
+                assert category == "general", \
+                    f"[{provider}] Key '{key}' expected general, got {category}"
+            else:
+                # Any key not explicitly expected should be model or general
+                assert category in ("model", "general", "eval", "policy"), \
+                    f"[{provider}] Key '{key}' got unexpected category {category}"
+
+
+# ---------------------------------------------------------------------------
+# Full fingerprint generation per provider
+# ---------------------------------------------------------------------------
+
+
+class TestPerProviderFingerprint:
+    """Verify that each provider's typical config produces the right hash categories."""
+
+    @pytest.mark.parametrize("provider,spec", list(PROVIDER_CONFIGS.items()))
+    def test_provider_fingerprint_has_model_hash(self, provider: str, spec: dict):
+        """Every provider config should produce a model hash (all have 'model' or equivalent)."""
+        builder = FingerprintBuilder(FingerprintConfig())
+        builder.record_node(f"{provider}_llm", "llm", spec["sample"], "system prompt")
+        fp = builder.get_fingerprint()
+
+        node = f"{provider}_llm"
+
+        # Every provider should have a model hash
+        assert node in fp.node_model_hashes, \
+            f"[{provider}] Expected model hash but got none. Config: {spec['sample']}"
+
+        # Combined hash should always be present (backward compat)
+        assert node in fp.node_config_hashes, \
+            f"[{provider}] Missing combined config hash"
+
+        # Prompt hash should be present
+        assert node in fp.node_prompt_hashes, \
+            f"[{provider}] Missing prompt hash"
+
+    @pytest.mark.parametrize("provider,spec", list(PROVIDER_CONFIGS.items()))
+    def test_provider_no_spurious_eval_or_policy(self, provider: str, spec: dict):
+        """Standard provider configs should NOT produce eval or policy hashes."""
+        builder = FingerprintBuilder(FingerprintConfig())
+        builder.record_node(f"{provider}_llm", "llm", spec["sample"])
+        fp = builder.get_fingerprint()
+
+        node = f"{provider}_llm"
+        expected_eval = spec.get("expected_eval_keys", set())
+        expected_policy = spec.get("expected_policy_keys", set())
+
+        if not expected_eval:
+            assert node not in fp.node_eval_config_hashes, \
+                f"[{provider}] Unexpected eval hash for standard config"
+        if not expected_policy:
+            assert node not in fp.node_policy_config_hashes, \
+                f"[{provider}] Unexpected policy hash for standard config"
+
+
+# ---------------------------------------------------------------------------
+# Cross-provider change detection isolation
+# ---------------------------------------------------------------------------
+
+
+class TestCrossProviderChangeIsolation:
+    """Verify that model changes are detected correctly across different providers."""
+
+    @pytest.mark.parametrize("provider,spec", list(PROVIDER_CONFIGS.items()))
+    def test_model_swap_detected_as_model_change(self, provider: str, spec: dict):
+        """Swapping the model name should change the model hash but not other hashes."""
+        config_v1 = dict(spec["sample"])
+        config_v2 = dict(spec["sample"])
+
+        # Find the model key for this provider
+        model_key = None
+        for k in spec["sample"]:
+            if classify_config_key(k) == "model" and "model" in k.lower():
+                model_key = k
+                break
+
+        if model_key is None:
+            pytest.skip(f"No model key found for {provider}")
+
+        config_v2[model_key] = "different-model-v2"
+
+        b1 = FingerprintBuilder(FingerprintConfig())
+        b1.record_node("llm", "llm", config_v1, "same prompt")
+        fp1 = b1.get_fingerprint()
+
+        b2 = FingerprintBuilder(FingerprintConfig())
+        b2.record_node("llm", "llm", config_v2, "same prompt")
+        fp2 = b2.get_fingerprint()
+
+        # Model hash MUST change
+        assert fp1.node_model_hashes["llm"] != fp2.node_model_hashes["llm"], \
+            f"[{provider}] Model hash should change when model is swapped"
+
+        # Prompt hash MUST NOT change
+        assert fp1.node_prompt_hashes["llm"] == fp2.node_prompt_hashes["llm"], \
+            f"[{provider}] Prompt hash should NOT change when only model swapped"
+
+    @pytest.mark.parametrize("provider,spec", list(PROVIDER_CONFIGS.items()))
+    def test_temperature_change_detected_as_model_change(self, provider: str, spec: dict):
+        """Changing temperature should change the model hash."""
+        if "temperature" not in spec["sample"]:
+            pytest.skip(f"No temperature for {provider}")
+
+        config_v1 = dict(spec["sample"])
+        config_v2 = dict(spec["sample"])
+        config_v2["temperature"] = 0.99  # changed
+
+        b1 = FingerprintBuilder(FingerprintConfig())
+        b1.record_node("llm", "llm", config_v1)
+        fp1 = b1.get_fingerprint()
+
+        b2 = FingerprintBuilder(FingerprintConfig())
+        b2.record_node("llm", "llm", config_v2)
+        fp2 = b2.get_fingerprint()
+
+        assert fp1.node_model_hashes["llm"] != fp2.node_model_hashes["llm"], \
+            f"[{provider}] Model hash should change when temperature changes"
+
+
+# ---------------------------------------------------------------------------
+# camelCase variant validation (critical for JS SDK / Bedrock / Google)
+# ---------------------------------------------------------------------------
+
+
+class TestCamelCaseKeyClassification:
+    """Ensure camelCase config keys from TypeScript SDKs classify correctly."""
+
+    @pytest.mark.parametrize("key,expected", [
+        # Google / Vertex AI (TS SDK uses camelCase)
+        ("maxOutputTokens", "model"),
+        ("topP", "model"),
+        ("topK", "model"),
+        ("candidateCount", "model"),
+        # LangChain / LangGraph (TS SDK)
+        ("modelName", "model"),
+        ("maxTokens", "model"),
+        ("modelKwargs", "model"),
+        # Bedrock (camelCase native)
+        ("modelId", "model"),
+        ("stopSequences", "model"),
+        # AutoGen TS
+        ("cacheSeed", "general"),
+        # LangGraph TS
+        ("recursionLimit", "general"),
+        # CrewAI / LlamaIndex TS
+        ("contextWindow", "model"),
+    ])
+    def test_camelcase_key(self, key: str, expected: str):
+        assert classify_config_key(key) == expected, \
+            f"Key '{key}' should classify as '{expected}' but got '{classify_config_key(key)}'"
+
+
+# ---------------------------------------------------------------------------
+# Eval and Policy augmented configs
+# ---------------------------------------------------------------------------
+
+
+class TestAugmentedConfigs:
+    """Test provider configs augmented with eval/policy keys.
+
+    In real workflows, users may add eval or policy config to their LLM nodes.
+    These should be detected separately from model changes.
+    """
+
+    def test_openai_with_eval_config(self):
+        config = {
+            "model": "gpt-4o",
+            "temperature": 0.7,
+            "eval_criteria": "helpfulness",
+            "eval_rubric": "1-5 scale",
+        }
+        builder = FingerprintBuilder(FingerprintConfig())
+        builder.record_node("llm", "llm", config)
+        fp = builder.get_fingerprint()
+
+        assert "llm" in fp.node_model_hashes
+        assert "llm" in fp.node_eval_config_hashes
+
+    def test_anthropic_with_guardrail(self):
+        config = {
+            "model": "claude-3-opus",
+            "temperature": 0.5,
+            "guardrail": "pii_filter",
+            "safety_threshold": 0.95,
+        }
+        builder = FingerprintBuilder(FingerprintConfig())
+        builder.record_node("llm", "llm", config)
+        fp = builder.get_fingerprint()
+
+        assert "llm" in fp.node_model_hashes
+        assert "llm" in fp.node_policy_config_hashes
+
+    def test_langchain_with_eval_and_policy(self):
+        config = {
+            "model_name": "gpt-4",
+            "temperature": 0.3,
+            "eval_model": "gpt-4o-mini",
+            "eval_criteria": "accuracy",
+            "guardrail_config": {"toxicity": True},
+        }
+        builder = FingerprintBuilder(FingerprintConfig())
+        builder.record_node("llm", "llm", config)
+        fp = builder.get_fingerprint()
+
+        assert "llm" in fp.node_model_hashes
+        assert "llm" in fp.node_eval_config_hashes
+        assert "llm" in fp.node_policy_config_hashes
+
+    def test_changing_eval_does_not_affect_model_hash(self):
+        config_v1 = {
+            "model": "gpt-4o",
+            "eval_criteria": "helpfulness",
+        }
+        config_v2 = {
+            "model": "gpt-4o",
+            "eval_criteria": "accuracy",  # changed
+        }
+
+        b1 = FingerprintBuilder(FingerprintConfig())
+        b1.record_node("llm", "llm", config_v1)
+        fp1 = b1.get_fingerprint()
+
+        b2 = FingerprintBuilder(FingerprintConfig())
+        b2.record_node("llm", "llm", config_v2)
+        fp2 = b2.get_fingerprint()
+
+        assert fp1.node_model_hashes["llm"] == fp2.node_model_hashes["llm"]
+        assert fp1.node_eval_config_hashes["llm"] != fp2.node_eval_config_hashes["llm"]

turingpulse_sdk-1.0.0/tests/test_double_instrumentation.py

@@ -0,0 +1,48 @@
+"""Tests for double-instrumentation prevention via _INSTRUMENTING context var."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from unittest.mock import MagicMock
+
+import pytest
+
+from turingpulse_sdk import init
+import turingpulse_sdk.plugin as pm
+
+
+@pytest.fixture(autouse=True)
+def setup():
+    pm._PLUGIN = None
+    plugin = init(api_key="dedup-key", workflow_name="dedup-test")
+    plugin.client = MagicMock()
+    plugin.client.emit_serialized_payload = MagicMock()
+    plugin.client.policy_check = MagicMock(return_value=MagicMock(action="allow", blocked=False))
+    yield plugin
+    pm._PLUGIN = None
+
+
+class TestInstrumentingGuard:
+    """Verify _INSTRUMENTING context var prevents nested double spans."""
+
+    def test_instrumenting_var_prevents_recursion(self):
+        from contextvars import ContextVar
+
+        guard: ContextVar[bool] = ContextVar("test_guard", default=False)
+        call_count = 0
+
+        def inner():
+            nonlocal call_count
+            if guard.get(False):
+                call_count += 1
+                return "skipped"
+            token = guard.set(True)
+            try:
+                call_count += 1
+                return inner()  # Recursive call should skip
+            finally:
+                guard.reset(token)
+
+        result = inner()
+        assert call_count == 2
+        assert result == "skipped"