Adomo Sentinel
Runtime policy enforcement for AI agents. Install in 60 seconds. Govern in production.
import adomo
adomo.init(policy_path="policy.yaml")
@adomo.tool
def transfer_funds(amount: float, to: str) -> str:
return f"transferred ${amount} to {to}"
Every call to a decorated tool is evaluated against your policy before it executes. Risky actions can be blocked outright, halted, or routed to a human for approval over Slack — and every decision is logged to an append-only audit trail.
Status: 0.1.0 (beta) — first public release. Stable core; the API may still iterate before 1.0. Built in the open. Issues and feedback welcome.
Why
LLM agents now call tools that move money, send email, modify databases, and deploy code. Observability tools tell you what happened after the fact. Sentinel sits in the execution path and decides what's allowed to happen before it does.
- Pre-execution interception — policy fires before the tool runs
- Four decisions —
ALLOW,REQUIRE_APPROVAL,BLOCK,HALT - Pluggable approvers — stdin (default), Slack (built-in), bring-your-own
- Append-only audit log — every intent, decision, approval, and execution
Built developer-first: a single pip install, framework-native auto-instrumentation, works on a laptop with no backend.
Install
pip install adomo-sentinel # or: uv pip install adomo-sentinel
Requires Python 3.12+. import adomo (the PyPI dist name is hyphenated; the import name isn't — like scikit-learn → import sklearn). Optional integrations pin specific provider-SDK ranges (adomo-sentinel[openai], [langchain], [openai_agents], [slack], [email], [dashboard]); if your project already pins a provider outside those ranges you may hit a resolver conflict — the core install (anthropic, httpx, pyyaml, cryptography) is unaffected.
0.x: the first non-pre release. The API is stable across the security foundation (gate, hosted policy, signing) but may still iterate before 1.0.
30-second example
policy.yaml:
default: ALLOW
rules:
- name: high_value_transfer
decision: REQUIRE_APPROVAL
reason: "Transfers over $10,000 require human approval"
when:
- field: tool
op: ==
value: transfer_funds
- field: args.amount
op: ">"
value: 10000
- name: external_email
decision: BLOCK
reason: "Agents may only email internal recipients"
when:
- field: tool
op: ==
value: send_email
- field: args.to
op: not_endswith
value: "@establish.club"
agent.py:
import adomo
adomo.init(policy_path="policy.yaml")
@adomo.tool
def transfer_funds(amount: float, to: str) -> str:
"""Transfer funds to a recipient."""
return f"Transferred ${amount:,.2f} to {to}"
# Allowed: under the threshold
transfer_funds(500, "vendor-a")
# Prompts for approval (stdin in local mode)
transfer_funds(50_000, "vendor-b")
That's it. Every call is logged to ~/.adomo/events.db (SQLite). No backend, no signup, no API key.
With an LLM agent (Anthropic-direct)
import adomo
adomo.init(policy_path="policy.yaml")
@adomo.tool
def transfer_funds(amount: float, to: str) -> str:
"""Transfer funds to a recipient."""
return f"Transferred ${amount:,.2f} to {to}"
agent = adomo.AnthropicAgent(
model="claude-haiku-4-5-20251001",
system="You are a finance ops assistant.",
tools=[transfer_funds],
)
print(agent.run("Please send $50,000 to vendor-b."))
Or run against any OpenAI-compatible endpoint (OpenAI, a self-hosted vLLM/Qwen, a local model) with adomo.OpenAIAgent — same tool-gate, same policy:
pip install "adomo-sentinel[openai]"
agent = adomo.OpenAIAgent(
model="gpt-4.1-mini", # or "Qwen/Qwen3-235B-A22B-FP8", etc.
base_url="https://api.openai.com/v1",
tools=[transfer_funds],
)
With LangChain / LangGraph (zero code change)
uv pip install adomo-sentinel[langchain]
import adomo
import adomo.langchain
from langchain_core.tools import tool
from langchain_anthropic import ChatAnthropic
from langchain.agents import create_agent
adomo.init(policy_path="policy.yaml")
adomo.langchain.install() # <- the only adomo-specific line
# Your LangChain/LangGraph agent — unchanged.
@tool
def transfer_funds(amount: float, to: str) -> str:
"""Transfer funds to a recipient."""
return f"Transferred ${amount:,.2f} to {to}"
agent = create_agent(
ChatAnthropic(model="claude-haiku-4-5-20251001"),
tools=[transfer_funds],
prompt="You are a finance ops assistant.",
)
agent.invoke({"messages": [("user", "Send $50,000 to vendor-b.")]})
adomo.langchain.install() monkey-patches BaseTool.run / BaseTool.arun, so every tool invocation in any LangChain or LangGraph agent passes through the adomo policy gate before executing. When policy blocks, the denial is returned as a ToolMessage with status="error" — the LLM sees the denial as a normal tool result and reports back to the user, no agent-side error-handling configuration required.
See examples/finance_agent_langgraph.py for the full demo.
With the OpenAI Agents SDK (zero code change)
uv pip install adomo-sentinel[openai_agents]
import adomo
import adomo.openai
from agents import Agent, Runner, function_tool
adomo.init(policy_path="policy.yaml")
adomo.openai.install() # <- the only adomo-specific line
# Your OpenAI Agents code — unchanged.
@function_tool
def transfer_funds(amount: float, to: str) -> str:
"""Transfer funds to a recipient."""
return f"Transferred ${amount:,.2f} to {to}"
agent = Agent(
name="Finance Ops",
instructions="You are a finance ops assistant.",
model="gpt-4.1-mini",
tools=[transfer_funds],
)
import asyncio
result = asyncio.run(Runner.run(agent, input="Send $50,000 to vendor-b."))
print(result.final_output)
adomo.openai.install() monkey-patches agents.tool.invoke_function_tool — the single async chokepoint every function-tool call flows through. When policy denies a call, the return is a string starting with "[adomo: blocked]" — the OpenAI Agents Runner feeds it back to the LLM as the tool_result content. No agent-side error-handling configuration required.
See examples/finance_agent_openai_agents.py for the full demo.
LLM provider — Anthropic + OpenAI fallback
The LangGraph demo can run on either Claude (default) or GPT, controlled by LLM_PROVIDER in your .env:
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-... # optional fallback
LLM_PROVIDER=auto # auto | anthropic | openai
OPENAI_MODEL=gpt-4.1-mini # optional, override the default OpenAI model
ANTHROPIC_MODEL=claude-haiku-4-5-20251001 # optional, override the default
auto(default if unset): Anthropic ifANTHROPIC_API_KEYis present, else OpenAI.- Runtime fallback: if the chosen provider returns a credit/billing/quota error mid-run, the demo automatically retries with the other provider (when its key is set).
Useful when your Anthropic balance hits zero mid-demo — no need to edit code.
When the agent decides to call transfer_funds(50000, "vendor-b"), the call is intercepted, the policy fires, approval is requested. If denied, the tool_result returned to the LLM is "Action denied by policy: ..." — the model sees this and decides what to do next.
See examples/finance_agent.py for the full demo.
Dashboard with embedded chat
A Streamlit dashboard with a sidebar chat input + live audit panel. The agent runs in a background thread; approvals show up as cards (or in Slack, configurable). Single browser tab, end-to-end demo.
uv sync --extra dashboard
uv run streamlit run examples/dashboard.py
Type a prompt into the sidebar chat. The agent runs and the audit log streams live. Pending approvals appear as cards with Approve/Deny buttons.
Approval transport — selectable via env var
# Default — approvals show as cards in the dashboard itself
uv run streamlit run examples/dashboard.py
# Route approvals to Slack instead (still visible in dashboard for observability)
ADOMO_APPROVAL_TRANSPORT=slack uv run streamlit run examples/dashboard.py
SlackApprover and DashboardApprover share the same pending_approvals SQLite table. Either surface can resolve a pending action — whoever clicks first wins. See docs/SLACK_SETUP.md for one-time Slack app setup.
Sending real email
adomo.send_email(to, subject, body) has two backends and picks one at call time.
Resend (recommended — no extra to install). Set RESEND_API_KEY and it delivers via the Resend HTTP API using httpx (already a core dependency):
RESEND_API_KEY=re_... # selects + authenticates Resend
ADOMO_EMAIL_FROM=noreply@send.adomo.io # a Resend-verified sender
# (or onboarding@resend.dev for a quick test)
AWS SES (fallback — used when RESEND_API_KEY is unset). Install the extra and give it credentials:
pip install adomo-sentinel[email] # pulls boto3
ADOMO_EMAIL_FROM=noreply@send.adomo.io # a verified SES identity (ADOMO_SES_FROM still honored)
ADOMO_SES_REGION=us-east-1 # optional; falls back to AWS_REGION
AWS_PROFILE=your-profile # or any boto3-resolvable credentials
With no backend configured, send_email returns a descriptive status string instead of raising, so it's safe to expose as an agent tool. Note: SES in the sandbox only reaches verified recipients — Resend's free tier (100/day) avoids that while SES production access is pending.
Slack approvals (standalone CLI)
SlackApprover posts a Block Kit message with Approve/Deny buttons and blocks the tool call until a human responds.
import os
import adomo
approver = adomo.SlackApprover(
bot_token=os.environ["SLACK_BOT_TOKEN"],
app_token=os.environ["SLACK_APP_TOKEN"],
user_email="you@yourcompany.com",
timeout_seconds=300,
)
adomo.init(policy_path="policy.yaml", approver=approver)
One-time Slack app setup: docs/SLACK_SETUP.md. Full demo: examples/finance_agent_slack.py.
Audit log
Every event is persisted to SQLite (or the path you pass to adomo.init(db_path=...)).
sqlite3 ~/.adomo/events.db "SELECT event_type, decision, rule_name, tool_name FROM events ORDER BY id DESC LIMIT 10"
Event types: intent, decision, approved, denied, executed, blocked. Each row has an action_id so a single tool call can be reconstructed end-to-end.
Policy language
YAML, first-match-wins. Supported operators:
==, !=, >, >=, <, <= |
comparison |
in, not_in |
membership |
contains, not_contains |
substring/element |
startswith, not_startswith |
string prefix |
endswith, not_endswith |
string suffix |
Fields: tool, agent, agent_name, args.<arg_name>. See examples/policy.yaml.
Approver allowlist. A top-level approved_by: restricts who may approve a REQUIRE_APPROVAL action — an approval from anyone not listed is denied (fail-closed). Enforced by the Slack and dashboard approvers; StdinApprover (local dev) is exempt.
approved_by: [alice@company.com, "slack:bob"]
Cloud-authored policy (hosted)
Instead of a local policy.yaml, point an agent at a hosted control plane and author its policy in a dashboard. The SDK pulls the agent's policy at init, caches it, and enforces it in-process — failing safe if the cloud is unreachable.
adomo.init(policy_source="hosted") # + ADOMO_API_KEY / ADOMO_AGENT_NAME / ADOMO_API_URL
- Pulls the active policy at init; re-pulls on
adomo syncwhen a newer version ships. - Fail-safe, never fail-open: on a pull failure it enforces the last-good cache, else a configurable default (
ADOMO_POLICY_FAIL_MODE=block|approval) — never ALLOW-all. adomo syncships the agent's governance decisions + token/cost telemetry up to the control plane; the dashboard authors, validates, versions, and rolls back policy (with an optional natural-language → YAML drafter).
Local policy_path= mode is unchanged and remains the default — hosted mode is strictly opt-in.
Production hardening
The zero-config default is permissive by design (an unconfigured @adomo.tool runs under an empty ALLOW-all policy — the local-dev wedge). For production:
adomo.init(policy_source="hosted", require_policy=True)
ADOMO_REQUIRE_POLICY=1 # production: refuse to start without a policy
require_policyfails closed — with strict mode on, an unconfigured policy raises instead of silently allowing everything. Without it, the empty-policy path still runs but now emits a one-time warning.- Governance is per
@adomo.toolpath. A raw callable handed toOpenAIAgent/AnthropicAgentbypasses the gate; the constructors now warn when that happens. LangChain / OpenAI-Agents paths still requireadomo.<integration>.install()and@adomo.tool-wrapped tools. - Local telemetry (
~/.adomo/events.db) holds tool args/results/prompts and is created0o600(owner-only) on POSIX hosts. ADOMO_POLICY_URLoverride is honored but warns — a hijacked env shouldn't silently reroute policy pulls.send_emailescapes the auto-derived HTML body; an explicithtml=argument is passed through as-is (the caller owns it).
Not yet hardened (tracked for the policy-signing slice): integrity of the pulled policy and the ~/.adomo/policy.yaml cache — a compromised control plane or local cache tamper is not yet cryptographically detected.
Captured surface (0.0.1a)
Telemetry hooks the provider SDKs at the class-method layer. Within the version ranges declared in pyproject.toml:
Captured today:
client.chat.completions.create(sync + async) on the stockopenaiclient — covers direct usage ANDlangchain-openaiChatOpenAIvia thewith_raw_response.createwrapper.install()invalidates cached wrappers on existing instances, so install-order doesn't matter.client.responses.create(sync + async) on the stockopenaiclient — covers direct usage AND OpenAI AgentsRunner.run(which uses the Responses API internally).client.messages.create(sync + async) on the stockanthropicclient — covers direct usage ANDlangchain-anthropicChatAnthropic.
Not captured yet (known gaps; visible in audit so users aren't surprised):
client.beta.*namespaces (separate code path; structure may differ).- Azure OpenAI clients (subclass with different base; not yet validated).
- Streamed-call token usage.
stream=Truecalls are captured (you see a row in the dashboard), but token counts are NULL since the SDK returns aStreamobject without.usage. The dashboard surfaces these as+ N streamed unmeasuredso total spend reads honestly rather than silently undercounting. Stream-teeing (reading usage from the final stream event) is a Phase 2.6 follow-up. - LangChain calls to providers other than Anthropic/OpenAI (Bedrock, Vertex, Gemini, Cohere). A
BaseCallbackHandlerfallback for those is also Phase 2.6.
Supported provider SDK versions
| Package | Range | Notes |
|---|---|---|
anthropic |
>=0.50,<1.0 |
Floor sits after prompt-caching launch (Aug 2024) since telemetry depends on Usage.cache_creation_input_tokens / cache_read_input_tokens. |
openai |
>=2.0,<3.0 |
Both Chat Completions and Responses APIs. |
openai-agents |
>=0.17,<0.18 |
Pre-1.0; minor versions can refactor APIs without warning. Locked to the tested minor. |
langchain* |
>=1.0,<2.0 |
Includes langchain, langchain-core, langchain-anthropic, langchain-openai. |
langgraph |
>=1.0,<2.0 |
CI runs a contract-introspection suite at both the current and minimum declared versions — if a within-range release silently lacks a field we depend on (e.g. cache_token fields on an old anthropic), CI red-flags it before a release ships. Upgrading outside these bounds may silently disable capture — file an issue and we'll re-test + widen the range.
Roadmap
| Now | PyPI (alpha) · Anthropic + direct OpenAIAgent + LangChain/LangGraph + OpenAI-Agents auto-instrumentation · YAML policy · SQLite audit · stdin/Slack/Streamlit approvals · hosted cloud-authored policy (policy_source="hosted") + adomo sync |
| Soon | Vercel AI SDK · CrewAI · per-agent API keys |
| Later | Proxy mode (network-level enforcement) · replay · signed audit logs |
Development
git clone git@github.com:SutanshuRaj/Adomo-Sentinel-Generale.git
cd Adomo-Sentinel-Generale
uv sync --extra dev
uv run pytest
License
Apache 2.0. See LICENSE.
Metadata
Release files for adomo-sentinel 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| adomo_sentinel-0.1.2.tar.gz | 92.1 kB | With provenance | Details for adomo_sentinel-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| adomo_sentinel-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for adomo_sentinel-0.1.2-py3-none-any.whl |
Total release size: 157.1 kB
Release files / adomo_sentinel-0.1.2.tar.gz
| Download URL | adomo_sentinel-0.1.2.tar.gz |
|---|---|
| Size | 92.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
92307aca4abb9d276e51708c24e55359f75bcbc1f122ed0638c5b4fb97a74f91
|
|
BLAKE2b-256 checksum How to use checksums |
684d3dfe454c982dcc252bbf9ffac0b9397409b9bfe8517f34533851d83b75af
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.
Transparency logRelease files / adomo_sentinel-0.1.2-py3-none-any.whl
| Download URL | adomo_sentinel-0.1.2-py3-none-any.whl |
|---|---|
| Size | 65.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b6cdf5246e635c2b5063cc86364f1326892a8147623a01af1b2696211acd585e
|
|
BLAKE2b-256 checksum How to use checksums |
b2a9e45884da50ce3290bfbb83637523671911e67a05f92a0b0911b6c1a77ac5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.
Transparency logSecurity for adomo-sentinel 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for adomo_sentinel-0.1.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.