metalins 0.4.0__tar.gz

metalins-0.4.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

metalins-0.4.0/LICENSE

@@ -0,0 +1,2 @@
+Apache License Version 2.0 — see ../LICENSE-Apache-2.0.txt at the monorepo root.
+Copyright 2026 Jose Hernandez (Metalins).

metalins-0.4.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: metalins
+Version: 0.4.0
+Summary: SDK for Metalins — identity verification for AI agents.
+Project-URL: Homepage, https://metalins.ai
+Project-URL: Repository, https://github.com/Metalins/metalins-python-sdk
+Author-email: Metalins <support@metalins.ai>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agents,ai,identity,metalins,verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: langchain-core>=0.3.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: starlette>=0.37.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110.0; extra == 'fastapi'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# metalins
+
+**Zero Trust identity verification for AI agents.**
+
+Your agents in production are black boxes. Metalins verifies they're still the same agents you deployed — same model, same behavior, continuously. It's the behavioral verification layer in the Zero Trust stack for AI agents.
+
+## How it works
+
+1. The SDK hashes your agent's inputs and outputs **locally** — raw prompts and responses never leave your infrastructure.
+2. Signed hashes are sent to `api.metalins.ai`, where the behavioral engine runs.
+3. The engine returns a continuous verification status: `verified`, `caution`, or `not_verified`.
+
+Your data stays in your infra. We only see fingerprints.
+
+## Install
+
+```bash
+pip install metalins
+```
+
+## Quick start
+
+Three lines to start verifying your agent:
+
+```python
+import metalins
+
+agent = metalins.Agent(api_key="ml_live_...", name="my-agent")
+agent.start()
+
+# Log each turn — hashing happens locally, automatically
+agent.log(input=user_message, output=agent_reply)
+
+# Check verification status at any time
+status = agent.get_status()  # "verified" | "caution" | "not_verified"
+```
+
+Or as a context manager:
+
+```python
+with metalins.Agent(api_key="ml_live_...", name="my-agent") as agent:
+    agent.log(input=user_message, output=agent_reply)
+```
+
+Get your API key at [metalins.ai](https://metalins.ai).
+
+## Integrations
+
+### LangChain
+
+```python
+from metalins import Agent
+from metalins.integrations.langchain import MetalinsCallbackHandler
+
+agent = Agent(api_key="ml_live_...", name="my-bot").start()
+handler = MetalinsCallbackHandler(agent)
+
+chain.invoke(user_input, config={"callbacks": [handler]})
+```
+
+Every chain and LLM call is logged automatically — no manual `agent.log()` needed.
+
+### FastAPI / Starlette
+
+```python
+import metalins
+from metalins.integrations.fastapi import MetalinsMiddleware
+
+agent = metalins.Agent(api_key="ml_live_...", name="my-api").start()
+app.add_middleware(MetalinsMiddleware, agent=agent)
+```
+
+Every request/response pair is logged automatically. Bodies are hashed locally and never buffered in full (1 MiB cap by default). Skip noisy endpoints with `exclude_paths=["/health"]`.
+
+### Anthropic SDK
+
+```python
+import metalins
+
+agent = metalins.Agent(api_key="ml_live_...", name="my-claude-agent").start()
+
+with metalins.trace(agent):
+    response = client.messages.create(...)
+```
+
+Or use the `@metalins.monitor` decorator on any function that calls the Anthropic SDK.
+
+## What leaves your infrastructure
+
+Only hashed fingerprints — never raw text:
+
+| What we receive | What stays with you |
+|-----------------|---------------------|
+| SHA-256 hash of input | Raw prompt text |
+| SHA-256 hash of output | Raw response text |
+| Timestamp + agent ID | Your users' data |
+| HMAC-signed event chain | Your model config |
+
+The behavioral engine compares fingerprint patterns over time. It does not reconstruct your prompts or responses.
+
+## State persistence
+
+The SDK persists the agent session (ID, secret, hash chain) to `~/.metalins/<name>.json` with `0600` permissions by default. To store it elsewhere — a database, a secrets manager — pass any object with `load()` and `save()`:
+
+```python
+agent = metalins.Agent(api_key="ml_live_...", name="my-bot", store=my_store)
+```
+
+## License
+
+Apache 2.0. See [LICENSE](LICENSE).

metalins-0.4.0/README.md

@@ -0,0 +1,111 @@
+# metalins
+
+**Zero Trust identity verification for AI agents.**
+
+Your agents in production are black boxes. Metalins verifies they're still the same agents you deployed — same model, same behavior, continuously. It's the behavioral verification layer in the Zero Trust stack for AI agents.
+
+## How it works
+
+1. The SDK hashes your agent's inputs and outputs **locally** — raw prompts and responses never leave your infrastructure.
+2. Signed hashes are sent to `api.metalins.ai`, where the behavioral engine runs.
+3. The engine returns a continuous verification status: `verified`, `caution`, or `not_verified`.
+
+Your data stays in your infra. We only see fingerprints.
+
+## Install
+
+```bash
+pip install metalins
+```
+
+## Quick start
+
+Three lines to start verifying your agent:
+
+```python
+import metalins
+
+agent = metalins.Agent(api_key="ml_live_...", name="my-agent")
+agent.start()
+
+# Log each turn — hashing happens locally, automatically
+agent.log(input=user_message, output=agent_reply)
+
+# Check verification status at any time
+status = agent.get_status()  # "verified" | "caution" | "not_verified"
+```
+
+Or as a context manager:
+
+```python
+with metalins.Agent(api_key="ml_live_...", name="my-agent") as agent:
+    agent.log(input=user_message, output=agent_reply)
+```
+
+Get your API key at [metalins.ai](https://metalins.ai).
+
+## Integrations
+
+### LangChain
+
+```python
+from metalins import Agent
+from metalins.integrations.langchain import MetalinsCallbackHandler
+
+agent = Agent(api_key="ml_live_...", name="my-bot").start()
+handler = MetalinsCallbackHandler(agent)
+
+chain.invoke(user_input, config={"callbacks": [handler]})
+```
+
+Every chain and LLM call is logged automatically — no manual `agent.log()` needed.
+
+### FastAPI / Starlette
+
+```python
+import metalins
+from metalins.integrations.fastapi import MetalinsMiddleware
+
+agent = metalins.Agent(api_key="ml_live_...", name="my-api").start()
+app.add_middleware(MetalinsMiddleware, agent=agent)
+```
+
+Every request/response pair is logged automatically. Bodies are hashed locally and never buffered in full (1 MiB cap by default). Skip noisy endpoints with `exclude_paths=["/health"]`.
+
+### Anthropic SDK
+
+```python
+import metalins
+
+agent = metalins.Agent(api_key="ml_live_...", name="my-claude-agent").start()
+
+with metalins.trace(agent):
+    response = client.messages.create(...)
+```
+
+Or use the `@metalins.monitor` decorator on any function that calls the Anthropic SDK.
+
+## What leaves your infrastructure
+
+Only hashed fingerprints — never raw text:
+
+| What we receive | What stays with you |
+|-----------------|---------------------|
+| SHA-256 hash of input | Raw prompt text |
+| SHA-256 hash of output | Raw response text |
+| Timestamp + agent ID | Your users' data |
+| HMAC-signed event chain | Your model config |
+
+The behavioral engine compares fingerprint patterns over time. It does not reconstruct your prompts or responses.
+
+## State persistence
+
+The SDK persists the agent session (ID, secret, hash chain) to `~/.metalins/<name>.json` with `0600` permissions by default. To store it elsewhere — a database, a secrets manager — pass any object with `load()` and `save()`:
+
+```python
+agent = metalins.Agent(api_key="ml_live_...", name="my-bot", store=my_store)
+```
+
+## License
+
+Apache 2.0. See [LICENSE](LICENSE).

metalins-0.4.0/docs/integrations/anthropic.md

@@ -0,0 +1,257 @@
+# Anthropic SDK Integration — metalins.trace and @metalins.monitor
+
+The Anthropic integration provides two primitives for recording Metalins
+verification events when calling the Anthropic SDK directly (no LangChain
+required):
+
+- **`metalins.trace(agent)`** — a context manager that wraps any block
+  containing Anthropic API calls.
+- **`@metalins.monitor(agent)`** — a decorator that wraps a function whose
+  first argument is the messages input and whose return value is the output.
+
+Both work for sync and async code, capture input/output, and call
+`agent.log(...)` exactly once per turn.
+
+## Installation
+
+```bash
+pip install metalins anthropic
+```
+
+No extra `metalins` optional-dependency is needed — the Anthropic integration
+module imports nothing from the `anthropic` package at load time. It works by
+duck-typing the response object, so it is compatible with any version of the
+Anthropic SDK.
+
+## Context Manager — `metalins.trace`
+
+### Sync Usage
+
+```python
+import anthropic
+import metalins
+
+agent = metalins.Agent(api_key="ml_live_...", name="my-claude-agent").start()
+client = anthropic.Anthropic()
+
+messages = [{"role": "user", "content": "Summarise this article: ..."}]
+
+with metalins.trace(agent) as t:
+    t.set_input(messages)                 # capture what you're sending
+    response = client.messages.create(
+        model="claude-opus-4-5",
+        max_tokens=1024,
+        messages=messages,
+    )
+    t.set_output(response)                # capture the Anthropic response
+```
+
+### Async Usage
+
+```python
+import anthropic
+import metalins
+
+agent = metalins.Agent(api_key="ml_live_...", name="my-async-agent").start()
+async_client = anthropic.AsyncAnthropic()
+
+async def handle_request(messages: list[dict]) -> str:
+    async with metalins.trace(agent) as t:
+        t.set_input(messages)
+        response = await async_client.messages.create(
+            model="claude-haiku-4-5",
+            max_tokens=512,
+            messages=messages,
+        )
+        t.set_output(response)
+    return response.content[0].text
+```
+
+### How the Context Manager Works
+
+```python
+with metalins.trace(agent) as t:
+    ...
+```
+
+`t` is a `TraceContext` object with two methods:
+
+| Method | Purpose |
+|--------|---------|
+| `t.set_input(value)` | Record the input for this turn. Accepts a list of message dicts, a string, bytes, or any JSON-serialisable object. |
+| `t.set_output(value)` | Record the output. Accepts an Anthropic `Message`, a plain string, or any JSON-serialisable object. Text is automatically extracted from `response.content[0].text`. |
+
+If the block raises an exception, **nothing is logged** — the exception
+propagates normally and the turn is treated as failed.
+
+## Decorator — `@metalins.monitor`
+
+Use `monitor` when you have a function dedicated to calling Claude. The first
+positional argument is captured as the input and the return value as the output.
+
+### Sync Decorator
+
+```python
+import anthropic
+import metalins
+
+agent = metalins.Agent(api_key="ml_live_...", name="classification-agent").start()
+client = anthropic.Anthropic()
+
+@metalins.monitor(agent)
+def classify_ticket(messages: list[dict]) -> str:
+    response = client.messages.create(
+        model="claude-haiku-4-5",
+        max_tokens=256,
+        messages=messages,
+    )
+    return response.content[0].text
+
+# Call normally — Metalins logs input + output automatically.
+result = classify_ticket([{"role": "user", "content": "My order never arrived."}])
+```
+
+### Async Decorator
+
+```python
+import anthropic
+import metalins
+
+agent = metalins.Agent(api_key="ml_live_...", name="refund-agent").start()
+async_client = anthropic.AsyncAnthropic()
+
+@metalins.monitor(agent)
+async def process_refund(messages: list[dict]) -> str:
+    response = await async_client.messages.create(
+        model="claude-opus-4-5",
+        max_tokens=1024,
+        messages=messages,
+    )
+    return response.content[0].text
+
+# In your async route / task:
+reply = await process_refund([{"role": "user", "content": "Refund order #42"}])
+```
+
+### What `monitor` Captures
+
+| Logged field | Source |
+|---|---|
+| `input` | The first positional argument (JSON-serialised if it's a list/dict) |
+| `output` | The return value — text extracted if it's an Anthropic Message, otherwise JSON-serialised |
+
+If the function raises, **nothing is logged**.
+
+## Configuration Options
+
+Both `trace` and `monitor` accept the same keyword arguments:
+
+```python
+metalins.trace(
+    agent,
+
+    # Extra key/values attached to the Metalins event.
+    metadata={"service": "refund-agent", "env": "prod"},
+
+    # Re-raise agent.log() failures. Default False — log failures are
+    # silenced so a Metalins outage never breaks your application.
+    raise_on_error=False,
+)
+
+@metalins.monitor(
+    agent,
+    metadata={"model": "claude-haiku-4-5"},
+    raise_on_error=False,
+)
+async def run(messages): ...
+```
+
+## Choosing Between `trace` and `monitor`
+
+| Scenario | Recommended primitive |
+|---|---|
+| Ad-hoc calls spread across a function body | `metalins.trace` context manager |
+| A dedicated function that calls Claude and returns its result | `@metalins.monitor` decorator |
+| Async FastAPI route that calls Claude directly | Either — `trace` gives more granular control |
+| Multi-step reasoning where you want one event per turn | `metalins.trace` — call `set_input`/`set_output` once per conversation turn |
+
+## Full Example — FastAPI Route with Async Anthropic
+
+```python
+import anthropic
+import metalins
+from fastapi import FastAPI
+from pydantic import BaseModel
+from contextlib import asynccontextmanager
+
+metalins_agent = metalins.Agent(api_key="ml_live_...", name="support-bot")
+anthropic_client = anthropic.AsyncAnthropic()
+
+
+@asynccontextmanager
+async def lifespan(app):
+    metalins_agent.start()
+    yield
+    metalins_agent.stop()
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+class ChatRequest(BaseModel):
+    messages: list[dict]
+
+
+@app.post("/chat")
+async def chat(req: ChatRequest):
+    async with metalins.trace(metalins_agent) as t:
+        t.set_input(req.messages)
+        response = await anthropic_client.messages.create(
+            model="claude-haiku-4-5",
+            max_tokens=1024,
+            messages=req.messages,
+        )
+        t.set_output(response)
+    return {"reply": response.content[0].text}
+```
+
+## Full Example — Decorator Pattern with Metadata
+
+```python
+import anthropic
+import metalins
+
+agent = metalins.Agent(api_key="ml_live_...", name="email-triage").start()
+client = anthropic.Anthropic()
+
+SYSTEM_PROMPT = "Classify the following support email into: billing, technical, general."
+
+
+@metalins.monitor(agent, metadata={"pipeline": "email-triage", "model": "claude-haiku-4-5"})
+def triage_email(messages: list[dict]) -> str:
+    response = client.messages.create(
+        model="claude-haiku-4-5",
+        max_tokens=128,
+        system=SYSTEM_PROMPT,
+        messages=messages,
+    )
+    return response.content[0].text
+
+
+category = triage_email([{"role": "user", "content": "I was charged twice this month."}])
+print(category)  # "billing"
+```
+
+## Error Handling
+
+```python
+# Default: swallow log errors (recommended for production)
+with metalins.trace(agent) as t:
+    ...  # agent.log() failure is silenced — your app keeps working
+
+# Opt in to raising: useful during local development
+with metalins.trace(agent, raise_on_error=True) as t:
+    ...  # will raise if agent.log() fails
+```
+
+The same option is available on `@metalins.monitor(agent, raise_on_error=True)`.