dymium 0.1.3

Dymium SDK for secure data and AI interactions

Python SDK (Reference)

This is the reference implementation. All other language SDKs must conform to the behavior defined here and in sdk/spec.

Package layout:

• dymium/core/ Contracts and shared utilities
• dymium/runtime/ SecureRuntime orchestration loop
• dymium/adapters/ Provider adapters (LLM, PII, MCP)
• dymium/tools/ Tool registry and execution boundaries
• dymium/types/ Generated types from sdk/spec

Hugging Face local PII detector (optional deps):

• dymium/adapters/pii/huggingface.py (HuggingFacePIIDetector)
• install extras: pip install "dymium[hf]"

Quick start (factory-based)

from dymium import SecureRuntime, RuntimeConfig

config = RuntimeConfig(
    model="openai:gpt-5",
    pii="dymium_hf",
    model_config={"api_key": "..."},
    pii_config={"model_id": "dymium/Dymium-NER-v1"},
    mcp={"base_url": "http://localhost:7000"},
)

runtime = SecureRuntime.from_config(config)

# Optional: stateful multi-turn session
session = runtime.session()
result = session.run("Hello! My SSN is 123-45-6789.")

Multiple MCP servers

from dymium import SecureRuntime, RuntimeConfig

config = RuntimeConfig(
    model="openai:gpt-5",
    pii="dymium_hf",
    model_config={"api_key": "..."},
    pii_config={"model_id": "dymium/Dymium-NER-v1"},
    mcp={
        "servers": [
            {"name": "ghost", "adapter": "mcp", "base_url": "http://ghostmcp.local", "api_key": "..."},
            {"name": "ext", "adapter": "mcp", "base_url": "http://localhost:7001"},
        ],
        "prefix_tools": True,
        "separator": "::",
    },
)

runtime = SecureRuntime.from_config(config)

Multi-turn (session)

from dymium import SecureRuntime, RuntimeConfig

runtime = SecureRuntime.from_config(RuntimeConfig(
    model="openai:gpt-5",
    pii="dymium_hf",
    model_config={"api_key": "..."},
    pii_config={"model_id": "dymium/Dymium-NER-v1"},
    mcp={"base_url": "http://localhost:7000"},
))

session = runtime.session()
session.run("My email is [e-mail].")
session.run("Can you summarize what I told you?")

Tool types (direct vs delegated)

Every tool must declare tool_type.

direct tools are non-agentic boundaries (local functions, DB/API calls, deterministic services).
direct tools must also declare input_mode:

• resolve: materialize originals only at execution time. Common resolve cases: identity/account lookups, order/ticket retrieval APIs, and parameterized DB queries keyed by sensitive identifiers.
• protect: keep placeholders in direct tool args.

delegated tools are agentic handoffs to another runtime (sub-agent or remote agent). Unlike direct, delegated handoffs cross into another LLM/tool loop outside the parent loop. Dymium keeps inputs protected and forwards runtime context instead of resolving originals at the parent boundary.

Policy location:

• SecureRuntime: set tool_type (and input_mode for direct tools) on each tool definition.
• Framework integrations: set tool.metadata["dymium"]["tool_type"] and tool.metadata["dymium"]["input_mode"] (required for direct tools).

Delegated handoffs use transport-managed delegation (delegated_transport / DelegatedTransport). Delegated context is runtime-managed by Dymium.

For SecureRuntime, delegated cross-instance calls can be automatic with delegated_transport on a local delegated tool (no custom handler needed). The runtime forwards dymium_context, including placeholderMap.

Remote delegated targets must also run Dymium security (another SecureRuntime instance or an integration path using Dymium sanitizer/middleware) to stay in the same security plane.

For integration-managed tools (LangChain/LangGraph/LlamaIndex), use DelegatedTransport. Keep tool signatures business-only; Dymium owns delegated context propagation internally. DelegatedTransport.as_tool_handler() is the simplest path for remote delegated calls without manual context plumbing.

Install (local dev)

From SDK/python:

pip install -e .

Examples

The examples/ directory includes four runnable demos:

• examples/secure_runtime_demo.py
• examples/langchain_demo.py
• examples/langgraph_demo.py
• examples/llamaindex_demo.py

All four examples use Dymium's Hugging Face detector with model id default:

• dymium/Dymium-NER-v1 (override with DYMIUM_PII_MODEL)

Example focus:

• secure_runtime_demo.py: runtime-config path with direct protect/resolve tools and a local delegated specialist tool.
• langchain_demo.py: middleware integration with direct protect/resolve tools and a local delegated specialist tool.
• langgraph_demo.py: graph integration with direct protect/resolve tools and a local delegated specialist tool.
• llamaindex_demo.py: workflow integration with direct protect/resolve tools and a local delegated specialist tool.

Run from SDK/python:

python examples/secure_runtime_demo.py
python examples/langchain_demo.py
python examples/langgraph_demo.py
python examples/llamaindex_demo.py

Publish (PyPI)

python -m build
twine upload dist/*