Metadata-Version: 2.4
Name: dymium
Version: 0.1.3
Summary: Dymium SDK for secure data and AI interactions
Author-email: "Dymium, Inc." <support@dymium.io>
Maintainer-email: Dymium SDK Team <support@dymium.io>
License-Expression: MIT
Project-URL: Homepage, https://www.dymium.io
Project-URL: Support, https://support.dymium.io
Project-URL: Security, https://support.dymium.io/hc/en-us/requests/new
Keywords: ai,pii,security,llm,mcp
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: pydantic>=2.0
Provides-Extra: test
Requires-Dist: mcp>=1.0.0; extra == "test"
Requires-Dist: langchain>=0.2.0; extra == "test"
Provides-Extra: hf
Requires-Dist: transformers>=4.41.0; extra == "hf"
Requires-Dist: torch>=2.2.0; extra == "hf"
Dynamic: license-file

# 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)

```python
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

```python
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)

```python
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 me@example.com.")
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/*
```
