enact-sdk 0.1.0__tar.gz

enact_sdk-0.1.0/LICENSE

@@ -0,0 +1,94 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not sell, resell, sublicense, or otherwise commercially distribute the
+software itself as a standalone product or as the primary component of a paid
+offering. For purposes of this restriction, "Sell" means practicing any or all
+of the rights granted to you under this license to provide to third parties,
+for a fee or other consideration, a product or service whose value derives
+entirely or substantially from the functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and otherwise transfer the software. This license does not cover
+any patent claims that you cause to be infringed by modifications or additions
+to the software. If you or your company make any written claim that the
+software infringes or contributes to infringement of any patent, your patent
+license for the software granted under these terms ends immediately.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license
+no later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+## Definitions
+
+The *licensor* is the entity offering these terms, and the *software* is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+*you* refers to the individual or entity agreeing to these terms.
+
+*your company* is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+*control* means ownership of substantially all the assets of an entity, or the
+power to direct its management and legal affairs.
+
+*your licenses* are all the licenses granted to you for the software under
+these terms.
+
+*use* includes any use of the software, including use in modified form.

enact_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: enact-sdk
+Version: 0.1.0
+Summary: An action firewall for AI agents
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary; extra == "postgres"
+Provides-Extra: github
+Requires-Dist: PyGithub; extra == "github"
+Provides-Extra: hubspot
+Requires-Dist: hubspot-api-client; extra == "hubspot"
+Provides-Extra: all
+Requires-Dist: psycopg2-binary; extra == "all"
+Requires-Dist: PyGithub; extra == "all"
+Requires-Dist: hubspot-api-client; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: responses; extra == "dev"
+Dynamic: license-file
+
+# Enact
+
+**An action firewall for AI agents.**
+
+Enact sits between your AI agent and the outside world. Every action goes through a policy gate first. If it passes, Enact executes it and returns a signed receipt. If it doesn't, nothing happens.
+
+```python
+from enact import EnactClient
+from enact.connectors.github import GitHubConnector
+from enact.workflows.agent_pr_workflow import agent_pr_workflow
+from enact.policies.git import no_push_to_main, require_branch_prefix
+
+enact = EnactClient(
+    systems={"github": GitHubConnector(token="...")},
+    policies=[no_push_to_main, require_branch_prefix(prefix="agent/")],
+    workflows=[agent_pr_workflow],
+)
+
+result, receipt = enact.run(
+    workflow="agent_pr_workflow",
+    actor_email="agent@company.com",
+    payload={"repo": "owner/repo", "branch": "agent/my-feature"},
+)
+```
+
+---
+
+## How It Works
+
+```
+agent calls enact.run()
+        │
+        ▼
+┌───────────────────┐
+│  Policy Gate      │  All policies run. Any failure = BLOCK.
+│  (pure Python,    │  No LLMs. Versioned in Git. Testable.
+│   no LLMs)        │
+└────────┬──────────┘
+    PASS │  BLOCK
+         │        └──▶ Receipt (decision=BLOCK, actions_taken=[])
+         ▼
+┌───────────────────┐
+│  Workflow runs    │  Enact executes the workflow against real systems.
+│  against real     │  Each action produces an ActionResult.
+│  systems          │
+└────────┬──────────┘
+         │
+         ▼
+┌───────────────────┐
+│  Signed Receipt   │  HMAC-SHA256 signed. Captures who/what/why/
+│                   │  pass-fail/what changed.
+└────────┬──────────┘
+         │
+         ▼
+  RunResult returned to agent
+```
+
+---
+
+## Three Things Enact Gives You
+
+1. **Vetted action allowlist** — agents can only call workflows you explicitly register
+2. **Deterministic policy engine** — plain Python functions, no LLMs, Git-versioned, fully testable
+3. **Human-readable receipts** — every run records who, what, why, pass/fail, and what changed
+
+---
+
+## What Enact Can Do Right Now
+
+### Policy enforcement
+- Block agents from pushing directly to `main` or `master`
+- Require branch names to match a prefix (e.g. `agent/`)
+- Cap how many files an agent can touch per commit
+- Restrict actions to a UTC time window (e.g. 2am–6am maintenance window), including midnight-crossing windows like 22:00–06:00
+- Block contractors from writing to PII fields
+- Require the actor to hold a specific role (`admin`, `engineer`, etc.)
+- Prevent duplicate contacts from being created in HubSpot (live lookup before the workflow runs)
+- Rate-limit how many tasks an agent creates per contact within a rolling time window
+
+### GitHub operations (via `GitHubConnector`)
+- Create a branch
+- Open a pull request
+- Create an issue
+- Delete a branch
+- Merge a pull request
+
+Every method is allowlisted at construction time — `GitHubConnector(token=..., allowlist=["create_branch", "create_pr"])` means the connector will refuse to call any method not on the list, even if the workflow tries.
+
+### Built-in workflows
+- **`agent_pr_workflow`** — creates a feature branch then opens a PR; aborts cleanly if branch creation fails so you never get a PR pointing at a non-existent branch
+- **`db_safe_insert`** — checks for a duplicate row before inserting; returns an explanatory failure instead of letting the database raise a constraint violation
+
+### Receipts
+Every run — pass or block — produces an HMAC-SHA256 signed JSON receipt written to `receipts/`. It captures: who ran what, the full payload, every policy result with its reason, the final decision, and a timestamp. `verify_signature()` lets you prove a receipt hasn't been tampered with after the fact.
+
+---
+
+## File Structure
+
+```
+enact/
+├── enact/                  # pip-installable package
+│   ├── __init__.py         # exports: EnactClient, all models
+│   ├── models.py           # data shapes for every object in a run
+│   ├── client.py           # EnactClient — orchestrates the full run() loop
+│   ├── policy.py           # policy engine — runs all checks, returns PolicyResult list
+│   ├── receipt.py          # builds, HMAC-signs, verifies, and writes receipts
+│   ├── connectors/
+│   │   ├── github.py       # GitHub: create_branch, create_pr, create_issue, delete_branch, merge_pr
+│   │   └── postgres.py     # Postgres: insert_row, update_row, select_rows, delete_row (planned v0.2)
+│   ├── workflows/
+│   │   ├── agent_pr_workflow.py   # create branch → open PR (never to main)
+│   │   └── db_safe_insert.py      # check constraints → insert row
+│   └── policies/
+│       ├── git.py          # no_push_to_main, max_files_per_commit, require_branch_prefix
+│       ├── crm.py          # no_duplicate_contacts, limit_tasks_per_contact
+│       ├── access.py       # contractor_cannot_write_pii, require_actor_role
+│       └── time.py         # within_maintenance_window
+├── tests/
+│   ├── test_policy_engine.py
+│   ├── test_receipt.py
+│   ├── test_client.py
+│   ├── test_github.py
+│   ├── test_git_policies.py
+│   ├── test_policies.py
+│   └── test_workflows.py
+├── examples/
+│   └── quickstart.py       # runnable demo — runs PASS then BLOCK, prints receipt
+├── receipts/               # auto-created at runtime, gitignored
+└── pyproject.toml          # PyPI config
+```
+
+### What each file does
+
+| File | Job |
+|------|-----|
+| `models.py` | Defines data shapes. `WorkflowContext` (inputs), `PolicyResult` (one policy check), `ActionResult` (one workflow action), `Receipt` (full signed run record), `RunResult` (what the agent gets back). |
+| `client.py` | The main entry point. `EnactClient.run()` builds context, runs policies, executes the workflow if PASS, writes the receipt, returns `RunResult`. |
+| `policy.py` | Runs every registered policy against `WorkflowContext`. Returns `list[PolicyResult]`. Never bails early — always runs all checks. |
+| `receipt.py` | Takes policy results + action results, builds a `Receipt`, signs it with HMAC-SHA256, writes it to `receipts/`. |
+| `connectors/` | Thin wrappers around vendor SDKs. Each connector exposes named actions (`create_branch`, `insert_row`, etc.) that workflows call. |
+| `workflows/` | Python functions that orchestrate connector actions. Each workflow step produces an `ActionResult`. |
+| `policies/` | Built-in reusable policy functions (ships with `pip install enact`). Each takes a `WorkflowContext` and returns a `PolicyResult`. |
+
+---
+
+## Data Flow (in code)
+
+```
+enact.run(workflow="agent_pr_workflow", actor_email="agent@co.com", payload={"repo": "owner/repo", "branch": "agent/fix"})
+  │
+  ├─▶ WorkflowContext(workflow, actor_email, payload, systems)
+  │
+  ├─▶ policy_results = [
+  │       PolicyResult(policy="no_push_to_main",      passed=True, reason="Branch is not main/master"),
+  │       PolicyResult(policy="require_branch_prefix", passed=True, reason="Branch 'agent/fix' has required prefix"),
+  │   ]
+  │
+  ├─▶ decision = PASS → execute workflow
+  │
+  ├─▶ actions_taken = [
+  │       ActionResult(action="create_branch", system="github", success=True, output={"branch": "agent/fix"}),
+  │       ActionResult(action="create_pr",     system="github", success=True, output={"pr_number": 42, "url": "..."}),
+  │   ]
+  │
+  ├─▶ Receipt(run_id, workflow, actor_email, payload, policy_results,
+  │           decision="PASS", actions_taken, timestamp, signature)
+  │
+  └─▶ RunResult(success=True, workflow="agent_pr_workflow", output={...})
+```
+
+---
+
+## Connectors (v0.1)
+
+| System | Actions | Status |
+|--------|---------|--------|
+| GitHub | `create_branch`, `create_pr`, `push_commit`, `delete_branch`, `create_issue`, `merge_pr` | ✅ v0.1 |
+| Postgres | `insert_row`, `update_row`, `select_rows`, `delete_row` | 🔜 v0.2 |
+| HubSpot | `create_contact`, `update_deal`, `create_task`, `get_contact` | 🔜 v0.2 |
+
+GitHub connector works with any repo accessible via a personal access token or GitHub App.
+
+---
+
+## Built-in Policies (v0.1)
+
+| File | Policy | What it blocks |
+|------|--------|----------------|
+| `git.py` | `no_push_to_main` | Any direct push to main/master |
+| `git.py` | `max_files_per_commit` | Commits touching too many files (blast radius) |
+| `git.py` | `require_branch_prefix` | Agent branches not prefixed correctly |
+| `crm.py` | `no_duplicate_contacts` | Creating a contact that already exists |
+| `crm.py` | `limit_tasks_per_contact` | Too many tasks created in a time window |
+| `access.py` | `contractor_cannot_write_pii` | Contractors writing PII fields |
+| `access.py` | `require_actor_role` | Actors without an allowed role |
+| `time.py` | `within_maintenance_window` | Actions outside allowed UTC time windows |
+
+---
+
+## Quickstart
+
+```bash
+git clone https://github.com/russellmiller3/enact
+cd enact
+pip install -e ".[dev]"
+python examples/quickstart.py
+```
+
+---
+
+## Run Tests
+
+```bash
+pytest tests/ -v
+# 96 tests, 0 failures
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `ENACT_SECRET` | `enact-default-secret` | HMAC signing key for receipts. Override in production. |
+| `GITHUB_TOKEN` | — | GitHub PAT for GitHubConnector |
+
+---
+
+## License
+
+[Elastic License 2.0 (ELv2)](./LICENSE)
+
+Free to use, modify, and redistribute. You may **not** offer Enact as a hosted
+or managed service, nor sell or resell the software itself as a product.
+See [LICENSE](./LICENSE) for full terms.

enact_sdk-0.1.0/README.md

@@ -0,0 +1,236 @@
+# Enact
+
+**An action firewall for AI agents.**
+
+Enact sits between your AI agent and the outside world. Every action goes through a policy gate first. If it passes, Enact executes it and returns a signed receipt. If it doesn't, nothing happens.
+
+```python
+from enact import EnactClient
+from enact.connectors.github import GitHubConnector
+from enact.workflows.agent_pr_workflow import agent_pr_workflow
+from enact.policies.git import no_push_to_main, require_branch_prefix
+
+enact = EnactClient(
+    systems={"github": GitHubConnector(token="...")},
+    policies=[no_push_to_main, require_branch_prefix(prefix="agent/")],
+    workflows=[agent_pr_workflow],
+)
+
+result, receipt = enact.run(
+    workflow="agent_pr_workflow",
+    actor_email="agent@company.com",
+    payload={"repo": "owner/repo", "branch": "agent/my-feature"},
+)
+```
+
+---
+
+## How It Works
+
+```
+agent calls enact.run()
+        │
+        ▼
+┌───────────────────┐
+│  Policy Gate      │  All policies run. Any failure = BLOCK.
+│  (pure Python,    │  No LLMs. Versioned in Git. Testable.
+│   no LLMs)        │
+└────────┬──────────┘
+    PASS │  BLOCK
+         │        └──▶ Receipt (decision=BLOCK, actions_taken=[])
+         ▼
+┌───────────────────┐
+│  Workflow runs    │  Enact executes the workflow against real systems.
+│  against real     │  Each action produces an ActionResult.
+│  systems          │
+└────────┬──────────┘
+         │
+         ▼
+┌───────────────────┐
+│  Signed Receipt   │  HMAC-SHA256 signed. Captures who/what/why/
+│                   │  pass-fail/what changed.
+└────────┬──────────┘
+         │
+         ▼
+  RunResult returned to agent
+```
+
+---
+
+## Three Things Enact Gives You
+
+1. **Vetted action allowlist** — agents can only call workflows you explicitly register
+2. **Deterministic policy engine** — plain Python functions, no LLMs, Git-versioned, fully testable
+3. **Human-readable receipts** — every run records who, what, why, pass/fail, and what changed
+
+---
+
+## What Enact Can Do Right Now
+
+### Policy enforcement
+- Block agents from pushing directly to `main` or `master`
+- Require branch names to match a prefix (e.g. `agent/`)
+- Cap how many files an agent can touch per commit
+- Restrict actions to a UTC time window (e.g. 2am–6am maintenance window), including midnight-crossing windows like 22:00–06:00
+- Block contractors from writing to PII fields
+- Require the actor to hold a specific role (`admin`, `engineer`, etc.)
+- Prevent duplicate contacts from being created in HubSpot (live lookup before the workflow runs)
+- Rate-limit how many tasks an agent creates per contact within a rolling time window
+
+### GitHub operations (via `GitHubConnector`)
+- Create a branch
+- Open a pull request
+- Create an issue
+- Delete a branch
+- Merge a pull request
+
+Every method is allowlisted at construction time — `GitHubConnector(token=..., allowlist=["create_branch", "create_pr"])` means the connector will refuse to call any method not on the list, even if the workflow tries.
+
+### Built-in workflows
+- **`agent_pr_workflow`** — creates a feature branch then opens a PR; aborts cleanly if branch creation fails so you never get a PR pointing at a non-existent branch
+- **`db_safe_insert`** — checks for a duplicate row before inserting; returns an explanatory failure instead of letting the database raise a constraint violation
+
+### Receipts
+Every run — pass or block — produces an HMAC-SHA256 signed JSON receipt written to `receipts/`. It captures: who ran what, the full payload, every policy result with its reason, the final decision, and a timestamp. `verify_signature()` lets you prove a receipt hasn't been tampered with after the fact.
+
+---
+
+## File Structure
+
+```
+enact/
+├── enact/                  # pip-installable package
+│   ├── __init__.py         # exports: EnactClient, all models
+│   ├── models.py           # data shapes for every object in a run
+│   ├── client.py           # EnactClient — orchestrates the full run() loop
+│   ├── policy.py           # policy engine — runs all checks, returns PolicyResult list
+│   ├── receipt.py          # builds, HMAC-signs, verifies, and writes receipts
+│   ├── connectors/
+│   │   ├── github.py       # GitHub: create_branch, create_pr, create_issue, delete_branch, merge_pr
+│   │   └── postgres.py     # Postgres: insert_row, update_row, select_rows, delete_row (planned v0.2)
+│   ├── workflows/
+│   │   ├── agent_pr_workflow.py   # create branch → open PR (never to main)
+│   │   └── db_safe_insert.py      # check constraints → insert row
+│   └── policies/
+│       ├── git.py          # no_push_to_main, max_files_per_commit, require_branch_prefix
+│       ├── crm.py          # no_duplicate_contacts, limit_tasks_per_contact
+│       ├── access.py       # contractor_cannot_write_pii, require_actor_role
+│       └── time.py         # within_maintenance_window
+├── tests/
+│   ├── test_policy_engine.py
+│   ├── test_receipt.py
+│   ├── test_client.py
+│   ├── test_github.py
+│   ├── test_git_policies.py
+│   ├── test_policies.py
+│   └── test_workflows.py
+├── examples/
+│   └── quickstart.py       # runnable demo — runs PASS then BLOCK, prints receipt
+├── receipts/               # auto-created at runtime, gitignored
+└── pyproject.toml          # PyPI config
+```
+
+### What each file does
+
+| File | Job |
+|------|-----|
+| `models.py` | Defines data shapes. `WorkflowContext` (inputs), `PolicyResult` (one policy check), `ActionResult` (one workflow action), `Receipt` (full signed run record), `RunResult` (what the agent gets back). |
+| `client.py` | The main entry point. `EnactClient.run()` builds context, runs policies, executes the workflow if PASS, writes the receipt, returns `RunResult`. |
+| `policy.py` | Runs every registered policy against `WorkflowContext`. Returns `list[PolicyResult]`. Never bails early — always runs all checks. |
+| `receipt.py` | Takes policy results + action results, builds a `Receipt`, signs it with HMAC-SHA256, writes it to `receipts/`. |
+| `connectors/` | Thin wrappers around vendor SDKs. Each connector exposes named actions (`create_branch`, `insert_row`, etc.) that workflows call. |
+| `workflows/` | Python functions that orchestrate connector actions. Each workflow step produces an `ActionResult`. |
+| `policies/` | Built-in reusable policy functions (ships with `pip install enact`). Each takes a `WorkflowContext` and returns a `PolicyResult`. |
+
+---
+
+## Data Flow (in code)
+
+```
+enact.run(workflow="agent_pr_workflow", actor_email="agent@co.com", payload={"repo": "owner/repo", "branch": "agent/fix"})
+  │
+  ├─▶ WorkflowContext(workflow, actor_email, payload, systems)
+  │
+  ├─▶ policy_results = [
+  │       PolicyResult(policy="no_push_to_main",      passed=True, reason="Branch is not main/master"),
+  │       PolicyResult(policy="require_branch_prefix", passed=True, reason="Branch 'agent/fix' has required prefix"),
+  │   ]
+  │
+  ├─▶ decision = PASS → execute workflow
+  │
+  ├─▶ actions_taken = [
+  │       ActionResult(action="create_branch", system="github", success=True, output={"branch": "agent/fix"}),
+  │       ActionResult(action="create_pr",     system="github", success=True, output={"pr_number": 42, "url": "..."}),
+  │   ]
+  │
+  ├─▶ Receipt(run_id, workflow, actor_email, payload, policy_results,
+  │           decision="PASS", actions_taken, timestamp, signature)
+  │
+  └─▶ RunResult(success=True, workflow="agent_pr_workflow", output={...})
+```
+
+---
+
+## Connectors (v0.1)
+
+| System | Actions | Status |
+|--------|---------|--------|
+| GitHub | `create_branch`, `create_pr`, `push_commit`, `delete_branch`, `create_issue`, `merge_pr` | ✅ v0.1 |
+| Postgres | `insert_row`, `update_row`, `select_rows`, `delete_row` | 🔜 v0.2 |
+| HubSpot | `create_contact`, `update_deal`, `create_task`, `get_contact` | 🔜 v0.2 |
+
+GitHub connector works with any repo accessible via a personal access token or GitHub App.
+
+---
+
+## Built-in Policies (v0.1)
+
+| File | Policy | What it blocks |
+|------|--------|----------------|
+| `git.py` | `no_push_to_main` | Any direct push to main/master |
+| `git.py` | `max_files_per_commit` | Commits touching too many files (blast radius) |
+| `git.py` | `require_branch_prefix` | Agent branches not prefixed correctly |
+| `crm.py` | `no_duplicate_contacts` | Creating a contact that already exists |
+| `crm.py` | `limit_tasks_per_contact` | Too many tasks created in a time window |
+| `access.py` | `contractor_cannot_write_pii` | Contractors writing PII fields |
+| `access.py` | `require_actor_role` | Actors without an allowed role |
+| `time.py` | `within_maintenance_window` | Actions outside allowed UTC time windows |
+
+---
+
+## Quickstart
+
+```bash
+git clone https://github.com/russellmiller3/enact
+cd enact
+pip install -e ".[dev]"
+python examples/quickstart.py
+```
+
+---
+
+## Run Tests
+
+```bash
+pytest tests/ -v
+# 96 tests, 0 failures
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `ENACT_SECRET` | `enact-default-secret` | HMAC signing key for receipts. Override in production. |
+| `GITHUB_TOKEN` | — | GitHub PAT for GitHubConnector |
+
+---
+
+## License
+
+[Elastic License 2.0 (ELv2)](./LICENSE)
+
+Free to use, modify, and redistribute. You may **not** offer Enact as a hosted
+or managed service, nor sell or resell the software itself as a product.
+See [LICENSE](./LICENSE) for full terms.

enact_sdk-0.1.0/enact/__init__.py

@@ -0,0 +1,19 @@
+"""Enact — an action firewall for AI agents."""
+
+from enact.client import EnactClient
+from enact.models import (
+    WorkflowContext,
+    PolicyResult,
+    ActionResult,
+    Receipt,
+    RunResult,
+)
+
+__all__ = [
+    "EnactClient",
+    "WorkflowContext",
+    "PolicyResult",
+    "ActionResult",
+    "Receipt",
+    "RunResult",
+]