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).
