edictum 0.4.0__tar.gz

edictum-0.4.0/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly

edictum-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev,yaml,sinks,cli]"
+      - run: pytest tests/ -v
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install ruff
+      - run: ruff check src/ tests/

edictum-0.4.0/.github/workflows/docs.yml

@@ -0,0 +1,38 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install mkdocs-material
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

edictum-0.4.0/.github/workflows/pr-title.yml

@@ -0,0 +1,24 @@
+name: PR Title
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        with:
+          types: |
+            feat
+            fix
+            docs
+            test
+            refactor
+            chore
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

edictum-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,17 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv publish

edictum-0.4.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+site/
+.coverage
+.pytest_cache/
+*.egg
+
+# Claude Code (personal config)
+CLAUDE.local
+.claude/
+
+# Internal research notes
+docs/ADAPTER_INSIGHTS.md
+docs/adapter-research.md

edictum-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

edictum-0.4.0/ARCHITECTURE.md

@@ -0,0 +1,114 @@
+# Edictum Architecture
+
+> Runtime safety for AI agents. Stop agents before they break things.
+
+## What It Does
+
+Edictum sits between an agent's decision to call a tool and actual execution. It enforces contracts, hooks, audit trails, and operation limits. When a rule is violated, it tells the agent **why** so it can self-correct.
+
+## Package Structure
+
+```
+src/edictum/
+├── __init__.py          # Edictum class, guard.run(), exceptions, re-exports
+├── envelope.py          # ToolEnvelope (frozen), SideEffect, ToolRegistry, BashClassifier
+├── hooks.py             # HookDecision (ALLOW/DENY)
+├── contracts.py         # Verdict, @precondition, @postcondition, @session_contract
+├── limits.py            # OperationLimits (attempt + execution + per-tool caps)
+├── pipeline.py          # GovernancePipeline — single source of governance logic
+├── session.py           # Session (atomic counters via StorageBackend)
+├── storage.py           # StorageBackend protocol + MemoryBackend
+├── audit.py             # AuditEvent, RedactionPolicy, Stdout/File sinks
+├── telemetry.py         # OpenTelemetry (graceful no-op if absent)
+├── builtins.py          # deny_sensitive_reads()
+├── types.py             # Internal types (HookRegistration, ToolConfig)
+└── adapters/
+    ├── langchain.py         # LangChain adapter (pre/post tool call hooks)
+    ├── crewai.py            # CrewAI adapter (before/after hooks)
+    ├── agno.py              # Agno adapter (wrap-around hook)
+    ├── semantic_kernel.py   # Semantic Kernel adapter (filter pattern)
+    ├── openai_agents.py     # OpenAI Agents SDK adapter (guardrails)
+    └── claude_agent_sdk.py  # Claude Agent SDK adapter (hook dict)
+```
+
+## The Flow
+
+Every tool call passes through:
+
+```
+Agent decides to call tool
+    │
+    ▼
+Adapter creates ToolEnvelope (deep-copied, classified)
+Increments attempt_count (BEFORE governance)
+    │
+    ▼
+Pipeline.pre_execute() — 5 steps:
+    1. Attempt limit (>= max_attempts?)
+    2. Before hooks (user-defined, can DENY)
+    3. Preconditions (contract checks, can DENY)
+    4. Session contracts (cross-turn state, can DENY)
+    5. Execution limits (>= max_tool_calls? per-tool?)
+    │
+    ├── DENY → audit event → tell agent why → agent self-corrects
+    │
+    └── ALLOW → tool executes
+                    │
+                    ▼
+            Pipeline.post_execute():
+                1. Postconditions (observe-only, warnings)
+                2. After hooks
+                3. Session record (exec count, consecutive failures)
+                    │
+                    ▼
+                Audit event (CALL_EXECUTED or CALL_FAILED)
+```
+
+## Key Design Decisions
+
+**Pipeline owns ALL governance logic.** Adapters are thin translation layers. Adding a second adapter doesn't fork governance behavior.
+
+**Two counter types:**
+- `max_attempts` — caps ALL PreToolUse events (including denied). Catches denial loops.
+- `max_tool_calls` — caps executions only (PostToolUse). Caps total work done.
+
+**Postconditions are observe-only.** They emit warnings, never block. For pure/read tools: suggest retry. For write/irreversible: warn only.
+
+**Observe mode** (`mode="observe"`): full pipeline runs, audit emits `CALL_WOULD_DENY`, but tool executes anyway. For shadow deployment.
+
+**Zero runtime deps.** OpenTelemetry via optional `edictum[otel]`.
+
+**Redaction at write time.** Destructive by design — no recovery. Sensitive keys, secret value patterns (OpenAI/AWS/JWT/GitHub/Slack), 32KB payload cap.
+
+**BashClassifier is a heuristic, not a security boundary.** Conservative READ allowlist + shell operator detection. Defense in depth with `deny_sensitive_reads()`.
+
+## Usage Modes
+
+**1. Framework-agnostic (`guard.run()`):**
+```python
+guard = Edictum(contracts=[deny_sensitive_reads()])
+result = await guard.run("Bash", {"command": "ls"}, my_bash_fn)
+```
+
+**2. Framework adapters (6 supported):**
+
+All adapters are thin translation layers — governance logic stays in the pipeline.
+
+```python
+from edictum.adapters.langchain import LangChainAdapter
+from edictum.adapters.crewai import CrewAIAdapter
+from edictum.adapters.agno import AgnoAdapter
+from edictum.adapters.semantic_kernel import SemanticKernelAdapter
+from edictum.adapters.openai_agents import OpenAIAgentsAdapter
+from edictum.adapters.claude_agent_sdk import ClaudeAgentSDKAdapter
+
+adapter = LangChainAdapter(guard, session_id="session-1")
+```
+
+## What This Is NOT
+
+- Not prompt injection defense
+- Not content safety filtering
+- Not network egress control
+- Not a security boundary for Bash
+- Not concurrency-safe across workers (MemoryBackend is single-process)

edictum-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arnold Cartagena
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

edictum-0.4.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: edictum
+Version: 0.4.0
+Summary: Runtime safety for AI agents. Stop agents before they break things.
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Provides-Extra: agno
+Requires-Dist: agno>=1.0; extra == 'agno'
+Provides-Extra: all
+Requires-Dist: agno>=1.0; extra == 'all'
+Requires-Dist: aiohttp>=3.9; extra == 'all'
+Requires-Dist: click>=8.0; extra == 'all'
+Requires-Dist: crewai>=0.80; extra == 'all'
+Requires-Dist: jsonschema>=4.20; extra == 'all'
+Requires-Dist: langchain-core>=0.3; extra == 'all'
+Requires-Dist: openai-agents>=0.1; extra == 'all'
+Requires-Dist: opentelemetry-api>=1.20; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'all'
+Requires-Dist: pyyaml>=6.0; extra == 'all'
+Requires-Dist: rich>=13.0; extra == 'all'
+Requires-Dist: semantic-kernel>=1.0; extra == 'all'
+Provides-Extra: cli
+Requires-Dist: click>=8.0; extra == 'cli'
+Requires-Dist: jsonschema>=4.20; extra == 'cli'
+Requires-Dist: pyyaml>=6.0; extra == 'cli'
+Requires-Dist: rich>=13.0; extra == 'cli'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.80; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: coverage>=7.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.1; extra == 'openai-agents'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
+Provides-Extra: semantic-kernel
+Requires-Dist: semantic-kernel>=1.0; extra == 'semantic-kernel'
+Provides-Extra: sinks
+Requires-Dist: aiohttp>=3.9; extra == 'sinks'
+Provides-Extra: yaml
+Requires-Dist: jsonschema>=4.20; extra == 'yaml'
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# Edictum
+
+[![PyPI](https://img.shields.io/pypi/v/edictum)](https://pypi.org/project/edictum/)
+[![License](https://img.shields.io/pypi/l/edictum)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/edictum)](https://pypi.org/project/edictum/)
+
+**Runtime contracts for AI agents.**
+
+AI agents make tool calls. Tool calls have side effects. Nobody governs what happens between "agent decides" and "tool executes." Edictum is that governance layer — preconditions, postconditions, session limits, and a full audit trail, enforced at the point where decision becomes action.
+
+## Show Me
+
+**contracts.yaml**
+
+```yaml
+apiVersion: edictum/v1
+kind: ContractBundle
+
+metadata:
+  name: my-policy
+
+defaults:
+  mode: enforce
+
+contracts:
+  - id: block-sensitive-reads
+    type: pre
+    tool: read_file
+    when:
+      args.path:
+        contains_any: [".env", ".secret", "credentials", ".pem", "id_rsa"]
+    then:
+      effect: deny
+      message: "Sensitive file '{args.path}' blocked."
+      tags: [secrets, dlp]
+```
+
+**Python**
+
+```python
+import asyncio
+from edictum import Edictum, EdictumDenied
+
+async def main():
+    guard = Edictum.from_yaml("contracts.yaml")
+
+    try:
+        result = await guard.run("read_file", {"path": "/app/config.json"}, read_file_fn)
+        print(result)
+    except EdictumDenied as e:
+        print(f"Denied: {e}")
+
+asyncio.run(main())
+```
+
+**CLI**
+
+```bash
+$ edictum validate contracts.yaml
+✓ contracts.yaml — 1 contract (1 pre)
+
+$ edictum check contracts.yaml --tool read_file --args '{"path": ".env"}'
+⛔ DENIED by block-sensitive-reads
+   Message: Sensitive file '.env' blocked.
+   Tags: secrets, dlp
+   Rules evaluated: 1
+```
+
+**Framework integration (one adapter, same guard)**
+
+```python
+from edictum.adapters.langchain import EdictumMiddleware
+
+middleware = EdictumMiddleware(guard)
+# Wraps any LangChain tool — preconditions, audit, and session limits apply automatically
+```
+
+## Features
+
+- **YAML contracts** — Preconditions, postconditions, and session limits declared in version-controlled YAML files
+- **6 framework adapters** — LangChain, CrewAI, Agno, Semantic Kernel, OpenAI Agents SDK, Claude Agent SDK
+- **Audit trail** — Structured JSON events with automatic redaction of secrets (OpenAI keys, AWS creds, JWTs, GitHub tokens)
+- **Observe mode** — Shadow-deploy contracts without blocking; review `CALL_WOULD_DENY` events before enforcing
+- **CLI tooling** — `validate`, `check`, `diff`, and `replay` commands for CI/CD integration
+- **Principal context** — Role, ticket ref, and claims propagated through every decision and audit event
+- **Session limits** — Cap total calls, attempts, and per-tool executions to catch runaway agents
+- **Zero runtime deps** — Pure Python 3.11+. OTel, sinks, and adapters are optional extras
+
+## How It Compares
+
+| Approach | Scope | Runtime enforcement | Audit trail |
+|---|---|---|---|
+| Prompt/output guardrails | Input/output text | No — advisory only | No |
+| API gateways / MCP proxies | Network transport | Yes — at the proxy | Partial |
+| Security scanners | Post-hoc analysis | No — detection only | Yes |
+| Manual if-statements | Per-tool, ad hoc | Yes — scattered logic | No |
+| **Edictum** | **Tool call contracts** | **Yes — deterministic pipeline** | **Yes — structured + redacted** |
+
+## Install
+
+```bash
+pip install edictum              # core (zero deps)
+pip install edictum[yaml]        # + YAML contract engine
+pip install edictum[sinks]       # + webhook, Splunk, Datadog sinks
+pip install edictum[cli]         # + validate/check/diff/replay CLI
+pip install edictum[all]         # everything
+```
+
+## Built-in Templates
+
+```python
+guard = Edictum.from_template("file-agent")      # secret file protection, destructive cmd blocking
+guard = Edictum.from_template("research-agent")   # output PII detection, session limits
+guard = Edictum.from_template("devops-agent")     # role gates, ticket requirements, bash safety
+```
+
+## Links
+
+- [Documentation](https://acartag7.github.io/edictum/)
+- [GitHub](https://github.com/acartag7/edictum)
+- [PyPI](https://pypi.org/project/edictum/)
+- [Changelog](CHANGELOG.md)
+- [License](LICENSE) (MIT)

edictum-0.4.0/README.md

@@ -0,0 +1,123 @@
+# Edictum
+
+[![PyPI](https://img.shields.io/pypi/v/edictum)](https://pypi.org/project/edictum/)
+[![License](https://img.shields.io/pypi/l/edictum)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/edictum)](https://pypi.org/project/edictum/)
+
+**Runtime contracts for AI agents.**
+
+AI agents make tool calls. Tool calls have side effects. Nobody governs what happens between "agent decides" and "tool executes." Edictum is that governance layer — preconditions, postconditions, session limits, and a full audit trail, enforced at the point where decision becomes action.
+
+## Show Me
+
+**contracts.yaml**
+
+```yaml
+apiVersion: edictum/v1
+kind: ContractBundle
+
+metadata:
+  name: my-policy
+
+defaults:
+  mode: enforce
+
+contracts:
+  - id: block-sensitive-reads
+    type: pre
+    tool: read_file
+    when:
+      args.path:
+        contains_any: [".env", ".secret", "credentials", ".pem", "id_rsa"]
+    then:
+      effect: deny
+      message: "Sensitive file '{args.path}' blocked."
+      tags: [secrets, dlp]
+```
+
+**Python**
+
+```python
+import asyncio
+from edictum import Edictum, EdictumDenied
+
+async def main():
+    guard = Edictum.from_yaml("contracts.yaml")
+
+    try:
+        result = await guard.run("read_file", {"path": "/app/config.json"}, read_file_fn)
+        print(result)
+    except EdictumDenied as e:
+        print(f"Denied: {e}")
+
+asyncio.run(main())
+```
+
+**CLI**
+
+```bash
+$ edictum validate contracts.yaml
+✓ contracts.yaml — 1 contract (1 pre)
+
+$ edictum check contracts.yaml --tool read_file --args '{"path": ".env"}'
+⛔ DENIED by block-sensitive-reads
+   Message: Sensitive file '.env' blocked.
+   Tags: secrets, dlp
+   Rules evaluated: 1
+```
+
+**Framework integration (one adapter, same guard)**
+
+```python
+from edictum.adapters.langchain import EdictumMiddleware
+
+middleware = EdictumMiddleware(guard)
+# Wraps any LangChain tool — preconditions, audit, and session limits apply automatically
+```
+
+## Features
+
+- **YAML contracts** — Preconditions, postconditions, and session limits declared in version-controlled YAML files
+- **6 framework adapters** — LangChain, CrewAI, Agno, Semantic Kernel, OpenAI Agents SDK, Claude Agent SDK
+- **Audit trail** — Structured JSON events with automatic redaction of secrets (OpenAI keys, AWS creds, JWTs, GitHub tokens)
+- **Observe mode** — Shadow-deploy contracts without blocking; review `CALL_WOULD_DENY` events before enforcing
+- **CLI tooling** — `validate`, `check`, `diff`, and `replay` commands for CI/CD integration
+- **Principal context** — Role, ticket ref, and claims propagated through every decision and audit event
+- **Session limits** — Cap total calls, attempts, and per-tool executions to catch runaway agents
+- **Zero runtime deps** — Pure Python 3.11+. OTel, sinks, and adapters are optional extras
+
+## How It Compares
+
+| Approach | Scope | Runtime enforcement | Audit trail |
+|---|---|---|---|
+| Prompt/output guardrails | Input/output text | No — advisory only | No |
+| API gateways / MCP proxies | Network transport | Yes — at the proxy | Partial |
+| Security scanners | Post-hoc analysis | No — detection only | Yes |
+| Manual if-statements | Per-tool, ad hoc | Yes — scattered logic | No |
+| **Edictum** | **Tool call contracts** | **Yes — deterministic pipeline** | **Yes — structured + redacted** |
+
+## Install
+
+```bash
+pip install edictum              # core (zero deps)
+pip install edictum[yaml]        # + YAML contract engine
+pip install edictum[sinks]       # + webhook, Splunk, Datadog sinks
+pip install edictum[cli]         # + validate/check/diff/replay CLI
+pip install edictum[all]         # everything
+```
+
+## Built-in Templates
+
+```python
+guard = Edictum.from_template("file-agent")      # secret file protection, destructive cmd blocking
+guard = Edictum.from_template("research-agent")   # output PII detection, session limits
+guard = Edictum.from_template("devops-agent")     # role gates, ticket requirements, bash safety
+```
+
+## Links
+
+- [Documentation](https://acartag7.github.io/edictum/)
+- [GitHub](https://github.com/acartag7/edictum)
+- [PyPI](https://pypi.org/project/edictum/)
+- [Changelog](CHANGELOG.md)
+- [License](LICENSE) (MIT)