clearframe 0.1.0__tar.gz

clearframe-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing to ClearFrame
+
+ClearFrame is Apache 2.0 licensed. All contributions are welcome.
+
+## Setup
+
+```bash
+git clone https://github.com/ibrahimmukherjee-boop/clearframe
+cd clearframe
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Running tests
+
+```bash
+pytest tests/ -v --cov=clearframe
+```
+
+## Code style
+
+```bash
+ruff check clearframe/ tests/
+mypy clearframe/
+```
+
+## Submitting a PR
+
+1. Fork the repo
+2. Create a branch: `git checkout -b feat/my-feature`
+3. Write tests for any new behaviour
+4. Run `pytest` and `ruff` — both must pass
+5. Open a PR with a clear description of the change
+
+## Reporting security issues
+
+Please **do not** open a public issue for security vulnerabilities.
+Email the maintainers directly or use GitHub's private security advisory feature.

clearframe-0.1.0/LICENSE

@@ -0,0 +1,58 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell,
+      import, and otherwise transfer the Work.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

clearframe-0.1.0/PKG-INFO

@@ -0,0 +1,295 @@
+Metadata-Version: 2.4
+Name: clearframe
+Version: 0.1.0
+Summary: Open-source AI agent protocol with auditability, safety controls, and a live AgentOps control plane.
+Project-URL: Homepage, https://github.com/ibrahimmukherjee-boop/clearframe
+Project-URL: Documentation, https://github.com/ibrahimmukherjee-boop/clearframe#readme
+Project-URL: Issues, https://github.com/ibrahimmukherjee-boop/clearframe/issues
+Author: ClearFrame Contributors
+License:                                  Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship made available under
+              the License, as indicated by a copyright notice that is included in
+              or attached to the work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              patent license to make, have made, use, offer to sell, sell,
+              import, and otherwise transfer the Work.
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+License-File: LICENSE
+Keywords: agentic,ai-agents,auditability,llm,mcp-alternative,safety
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4.3
+Requires-Dist: cryptography>=42.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Requires-Dist: rich>=13.7
+Requires-Dist: typer[all]>=0.12
+Requires-Dist: uvicorn[standard]>=0.29
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.1; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ClearFrame
+
+> The open-source AI agent protocol built for auditability, safety, and control.
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://python.org)
+[![Status](https://img.shields.io/badge/status-alpha-orange.svg)]()
+
+ClearFrame is a drop-in alternative to OpenClaw and MCP that puts **you** in control of your AI agents. Every tool call is scored for alignment, every reasoning step is captured, every credential is encrypted, and every action is logged to a tamper-evident audit trail.
+
+---
+
+## Why ClearFrame?
+
+| Problem with OpenClaw / MCP | ClearFrame's answer |
+|---|---|
+| Single process reads untrusted content AND executes tools → prompt injection | **Reader/Actor isolation** — two sandboxed processes, typed pipe between them |
+| Credentials stored in plaintext `~/.env` | **Encrypted Vault** — AES-256-GCM, memory-locked, auto-locks on session end |
+| No audit trail — forensics impossible | **HMAC-chained Audit Log** — tamper-evident, cryptographically verifiable |
+| No concept of what the agent is *supposed* to do | **Goal Monitor** — every tool call scored for alignment; drift triggers auto-pause |
+| Chain-of-thought never captured | **Reasoning Transparency Layer (RTL)** — full trace as queryable JSON |
+| No visibility into what context the model received | **Context Feed Auditor** — every token source-tagged and hashed |
+| No operator control plane | **AgentOps** — live REST + WebSocket dashboard to approve, block, or tweak |
+| Plugin ecosystem with no signing or review | **Signed Plugin Registry** — Ed25519 signatures, hash pinning, sandboxed execution |
+
+---
+
+## Quick Start
+
+```bash
+pip install clearframe
+
+# Initialise a new agent project
+clearframe init my-agent
+cd my-agent
+
+# Edit agent.py, then run
+python agent.py
+```
+
+### Minimal example
+
+```python
+import asyncio
+from clearframe import AgentSession, ClearFrameConfig
+from clearframe.core.manifest import GoalManifest, ToolPermission
+
+async def main():
+    config = ClearFrameConfig()
+    manifest = GoalManifest(
+        goal="Search for the latest AI safety papers and summarise them",
+        permitted_tools=[
+            ToolPermission(tool_name="web_search", max_calls_per_session=5),
+        ],
+    )
+    async with AgentSession(config, manifest) as session:
+        result = await session.call_tool("web_search", query="AI safety 2026")
+        print(result)
+
+asyncio.run(main())
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      AgentSession                           │
+│                                                             │
+│  ┌──────────────┐   typed pipe   ┌──────────────────────┐  │
+│  │ ReaderSandbox│ ─────────────► │    ActorSandbox       │  │
+│  │ (untrusted   │                │ (tool execution only) │  │
+│  │  content)    │                │ never reads raw input │  │
+│  └──────────────┘                └──────────────────────┘  │
+│         │                                  │                │
+│         ▼                                  ▼                │
+│  ┌──────────────┐              ┌───────────────────────┐   │
+│  │Context Feed  │              │     Goal Monitor       │   │
+│  │Auditor       │              │  alignment scoring     │   │
+│  │source-tags + │              │  auto-pause on drift   │   │
+│  │hashes every  │              │  operator queue        │   │
+│  │token         │              └───────────────────────┘   │
+│  └──────────────┘                          │                │
+│                                            ▼                │
+│                              ┌───────────────────────┐     │
+│                              │  RTL (Reasoning        │     │
+│                              │  Transparency Layer)   │     │
+│                              │  hash-verified traces  │     │
+│                              └───────────────────────┘     │
+│                                            │                │
+│                                            ▼                │
+│                              ┌───────────────────────┐     │
+│                              │  HMAC-Chained Audit   │     │
+│                              │  Log (tamper-evident) │     │
+│                              └───────────────────────┘     │
+└─────────────────────────────────────────────────────────────┘
+                                             │
+                                             ▼
+                              ┌───────────────────────┐
+                              │    AgentOps Server     │
+                              │  REST + WebSocket      │
+                              │  localhost:7477        │
+                              └───────────────────────┘
+```
+
+---
+
+## Core Concepts
+
+### GoalManifest
+Declare **what the agent is allowed to do** before it starts. The runtime enforces it.
+
+```python
+from clearframe.core.manifest import GoalManifest, ToolPermission, ResourceScope
+
+manifest = GoalManifest(
+    goal="Book a flight to London for next Friday",
+    permitted_tools=[
+        ToolPermission(tool_name="web_search", max_calls_per_session=10),
+        ToolPermission(tool_name="web_fetch", max_calls_per_session=5),
+        ToolPermission(tool_name="send_email", max_calls_per_session=1, require_approval=True),
+    ],
+    allow_file_write=False,
+    allow_code_execution=False,
+    max_steps=30,
+    resource_scope=ResourceScope(
+        allowed_domains=["flights.example.com", "*.airline.com"],
+    ),
+)
+```
+
+### Vault
+Never store credentials in plaintext again.
+
+```python
+from clearframe.core.vault import Vault
+from clearframe.core.config import VaultConfig
+
+vault = Vault(VaultConfig())
+vault.unlock("your-master-password")
+vault.set("openai_api_key", "sk-...")
+key = vault.get("openai_api_key")
+vault.lock()  # auto-zeroises memory
+```
+
+### Audit Log
+Cryptographically verify nothing was tampered with.
+
+```bash
+clearframe audit-verify
+# ✓ Audit log integrity verified — no tampering detected.
+
+clearframe audit-tail --lines 50
+```
+
+### AgentOps Server
+Start the live control plane:
+
+```bash
+clearframe ops-start
+# AgentOps running at http://localhost:7477
+# Auth token: <printed once to console>
+```
+
+---
+
+## CLI Reference
+
+```
+clearframe init <name>          Create a new agent project
+clearframe audit-verify         Verify audit log HMAC chain integrity
+clearframe audit-tail           Show recent audit entries
+clearframe ops-start            Start AgentOps control plane
+clearframe version              Show version
+```
+
+---
+
+## Comparison vs OpenClaw / MCP
+
+| Feature | OpenClaw | MCP | **ClearFrame** |
+|---|---|---|---|
+| Reader/Actor isolation | ✗ | ✗ | ✅ |
+| Goal alignment scoring | ✗ | ✗ | ✅ |
+| Reasoning trace capture | ✗ | Partial | ✅ Full JSON |
+| Tamper-evident audit log | ✗ | ✗ | ✅ HMAC chain |
+| Encrypted credential vault | ✗ | ✗ | ✅ AES-256-GCM |
+| Context feed hashing | ✗ | ✗ | ✅ |
+| Live operator control plane | ✗ | ✗ | ✅ |
+| Signed plugin registry | ✗ | ✗ | ✅ Ed25519 |
+| Auto-pause on drift | ✗ | ✗ | ✅ |
+| Open source | ✅ | ✅ | ✅ Apache 2.0 |
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). All contributions welcome — open an issue first for large changes.
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

clearframe-0.1.0/README.md

@@ -0,0 +1,203 @@
+# ClearFrame
+
+> The open-source AI agent protocol built for auditability, safety, and control.
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://python.org)
+[![Status](https://img.shields.io/badge/status-alpha-orange.svg)]()
+
+ClearFrame is a drop-in alternative to OpenClaw and MCP that puts **you** in control of your AI agents. Every tool call is scored for alignment, every reasoning step is captured, every credential is encrypted, and every action is logged to a tamper-evident audit trail.
+
+---
+
+## Why ClearFrame?
+
+| Problem with OpenClaw / MCP | ClearFrame's answer |
+|---|---|
+| Single process reads untrusted content AND executes tools → prompt injection | **Reader/Actor isolation** — two sandboxed processes, typed pipe between them |
+| Credentials stored in plaintext `~/.env` | **Encrypted Vault** — AES-256-GCM, memory-locked, auto-locks on session end |
+| No audit trail — forensics impossible | **HMAC-chained Audit Log** — tamper-evident, cryptographically verifiable |
+| No concept of what the agent is *supposed* to do | **Goal Monitor** — every tool call scored for alignment; drift triggers auto-pause |
+| Chain-of-thought never captured | **Reasoning Transparency Layer (RTL)** — full trace as queryable JSON |
+| No visibility into what context the model received | **Context Feed Auditor** — every token source-tagged and hashed |
+| No operator control plane | **AgentOps** — live REST + WebSocket dashboard to approve, block, or tweak |
+| Plugin ecosystem with no signing or review | **Signed Plugin Registry** — Ed25519 signatures, hash pinning, sandboxed execution |
+
+---
+
+## Quick Start
+
+```bash
+pip install clearframe
+
+# Initialise a new agent project
+clearframe init my-agent
+cd my-agent
+
+# Edit agent.py, then run
+python agent.py
+```
+
+### Minimal example
+
+```python
+import asyncio
+from clearframe import AgentSession, ClearFrameConfig
+from clearframe.core.manifest import GoalManifest, ToolPermission
+
+async def main():
+    config = ClearFrameConfig()
+    manifest = GoalManifest(
+        goal="Search for the latest AI safety papers and summarise them",
+        permitted_tools=[
+            ToolPermission(tool_name="web_search", max_calls_per_session=5),
+        ],
+    )
+    async with AgentSession(config, manifest) as session:
+        result = await session.call_tool("web_search", query="AI safety 2026")
+        print(result)
+
+asyncio.run(main())
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      AgentSession                           │
+│                                                             │
+│  ┌──────────────┐   typed pipe   ┌──────────────────────┐  │
+│  │ ReaderSandbox│ ─────────────► │    ActorSandbox       │  │
+│  │ (untrusted   │                │ (tool execution only) │  │
+│  │  content)    │                │ never reads raw input │  │
+│  └──────────────┘                └──────────────────────┘  │
+│         │                                  │                │
+│         ▼                                  ▼                │
+│  ┌──────────────┐              ┌───────────────────────┐   │
+│  │Context Feed  │              │     Goal Monitor       │   │
+│  │Auditor       │              │  alignment scoring     │   │
+│  │source-tags + │              │  auto-pause on drift   │   │
+│  │hashes every  │              │  operator queue        │   │
+│  │token         │              └───────────────────────┘   │
+│  └──────────────┘                          │                │
+│                                            ▼                │
+│                              ┌───────────────────────┐     │
+│                              │  RTL (Reasoning        │     │
+│                              │  Transparency Layer)   │     │
+│                              │  hash-verified traces  │     │
+│                              └───────────────────────┘     │
+│                                            │                │
+│                                            ▼                │
+│                              ┌───────────────────────┐     │
+│                              │  HMAC-Chained Audit   │     │
+│                              │  Log (tamper-evident) │     │
+│                              └───────────────────────┘     │
+└─────────────────────────────────────────────────────────────┘
+                                             │
+                                             ▼
+                              ┌───────────────────────┐
+                              │    AgentOps Server     │
+                              │  REST + WebSocket      │
+                              │  localhost:7477        │
+                              └───────────────────────┘
+```
+
+---
+
+## Core Concepts
+
+### GoalManifest
+Declare **what the agent is allowed to do** before it starts. The runtime enforces it.
+
+```python
+from clearframe.core.manifest import GoalManifest, ToolPermission, ResourceScope
+
+manifest = GoalManifest(
+    goal="Book a flight to London for next Friday",
+    permitted_tools=[
+        ToolPermission(tool_name="web_search", max_calls_per_session=10),
+        ToolPermission(tool_name="web_fetch", max_calls_per_session=5),
+        ToolPermission(tool_name="send_email", max_calls_per_session=1, require_approval=True),
+    ],
+    allow_file_write=False,
+    allow_code_execution=False,
+    max_steps=30,
+    resource_scope=ResourceScope(
+        allowed_domains=["flights.example.com", "*.airline.com"],
+    ),
+)
+```
+
+### Vault
+Never store credentials in plaintext again.
+
+```python
+from clearframe.core.vault import Vault
+from clearframe.core.config import VaultConfig
+
+vault = Vault(VaultConfig())
+vault.unlock("your-master-password")
+vault.set("openai_api_key", "sk-...")
+key = vault.get("openai_api_key")
+vault.lock()  # auto-zeroises memory
+```
+
+### Audit Log
+Cryptographically verify nothing was tampered with.
+
+```bash
+clearframe audit-verify
+# ✓ Audit log integrity verified — no tampering detected.
+
+clearframe audit-tail --lines 50
+```
+
+### AgentOps Server
+Start the live control plane:
+
+```bash
+clearframe ops-start
+# AgentOps running at http://localhost:7477
+# Auth token: <printed once to console>
+```
+
+---
+
+## CLI Reference
+
+```
+clearframe init <name>          Create a new agent project
+clearframe audit-verify         Verify audit log HMAC chain integrity
+clearframe audit-tail           Show recent audit entries
+clearframe ops-start            Start AgentOps control plane
+clearframe version              Show version
+```
+
+---
+
+## Comparison vs OpenClaw / MCP
+
+| Feature | OpenClaw | MCP | **ClearFrame** |
+|---|---|---|---|
+| Reader/Actor isolation | ✗ | ✗ | ✅ |
+| Goal alignment scoring | ✗ | ✗ | ✅ |
+| Reasoning trace capture | ✗ | Partial | ✅ Full JSON |
+| Tamper-evident audit log | ✗ | ✗ | ✅ HMAC chain |
+| Encrypted credential vault | ✗ | ✗ | ✅ AES-256-GCM |
+| Context feed hashing | ✗ | ✗ | ✅ |
+| Live operator control plane | ✗ | ✗ | ✅ |
+| Signed plugin registry | ✗ | ✗ | ✅ Ed25519 |
+| Auto-pause on drift | ✗ | ✗ | ✅ |
+| Open source | ✅ | ✅ | ✅ Apache 2.0 |
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). All contributions welcome — open an issue first for large changes.
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

clearframe-0.1.0/clearframe/__init__.py

@@ -0,0 +1,13 @@
+"""
+ClearFrame — Open-source AI agent protocol with auditability,
+goal monitoring, Reader/Actor isolation, and safety controls.
+
+A production-grade alternative to OpenClaw and MCP.
+"""
+
+from clearframe.core.config import ClearFrameConfig
+from clearframe.core.manifest import GoalManifest
+from clearframe.core.session import AgentSession
+
+__version__ = "0.1.0"
+__all__ = ["ClearFrameConfig", "GoalManifest", "AgentSession", "__version__"]