Metadata-Version: 2.4
Name: scyvera
Version: 1.0.0
Summary: Framework-independent contracts and validation tooling for AI agents and automated workflows.
Author: Shinjan Das
License-Expression: MIT
Project-URL: Repository, https://github.com/Skull-boy/agent-contracts
Project-URL: Issues, https://github.com/Skull-boy/agent-contracts/issues
Keywords: agent,contracts,governance,validation,schema,specification,automation,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML<7.0,>=6.0
Requires-Dist: jsonschema<5.0,>=4.20
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

<div align="center">

<img src="assets/logo.png" width="450" alt="agent-contracts"/>

# Scyvera

**Machine-readable, domain-independent, and framework-independent operational contracts for AI agents and automated systems.**

MCP and A2A standardize how agents communicate with tools and each other. `Scyvera` defines the layer above: what an intelligent system can do, what resources it can access, what authority it requires, what constraints apply, what side effects it produces, and how it is governed.

![License](https://img.shields.io/github/license/Skull-boy/agent-contracts)
![Stars](https://img.shields.io/github/stars/Skull-boy/agent-contracts)
![Issues](https://img.shields.io/github/issues/Skull-boy/agent-contracts)
![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)

</div>


---

## 🧩 What This Actually Is

`Scyvera` provides a machine-readable specification and Python tooling layer for defining the operational boundary of intelligent or automated systems.

It is **NOT**:
- another agent framework
- an LLM wrapper
- an orchestration library
- a coding-agent framework
- a security sandbox or malware scanner

It **IS**:
A framework-independent and domain-independent specification layer describing system identity, capabilities, resources, inputs, outputs, permissions, constraints, side effects, approvals, dependencies, state persistence, failure recovery, replay semantics, observability, artifact trust declarations, and risk.

---

## 🛡️ Validation vs. Runtime Enforcement

Scyvera provides two complementary governance layers:

| Layer | Component | Responsibility | Trust Level |
|---|---|---|---|
| **Tier 1 & 2: Static Verification** | `validate_contract()`, `lint_contract()` | Validates that a `contract.yaml` is structurally and semantically well-formed against specification schemas. | Declaration conformance |
| **Runtime Enforcement** | `ContractEnforcer` | Gates real-world Python calls against declared permissions and side effects using **Default-Deny** rules. Halts execution on approval points. | Execution boundary enforcement |

---

## ⚡ Quickstart

### 1. Installation

Install locally or in your project virtualenv:

```bash
pip install scyvera
# Or for local development:
pip install -e .
```

### 2. Command-Line Interface (CLI)

#### Create a starter Contract template (v1.1)
```bash
scyvera init contract.yaml --name "Research Assistant"
```

Interactive wizard mode:
```bash
scyvera init contract.yaml -i
```

#### Validate an Agent Contract
The CLI automatically detects the specification version (`1` vs `1.1`) and validates against the corresponding JSON Schema:
```bash
scyvera validate contract.yaml
```

Output:
```text
PASS  contract.yaml
```

Override with a custom JSON Schema file:
```bash
scyvera validate contract.yaml --schema path/to/custom.schema.json
```

---

## 🔒 Runtime Enforcer Quickstart

The `ContractEnforcer` protects your agent's execution boundaries in Python by enforcing **Default-Deny**: any undeclared permission or side effect raises `ContractViolationError`, and any action listed in `approval_points` raises `ApprovalPendingError`.

```python
from pathlib import Path
from scyvera import ContractEnforcer, ContractViolationError, ApprovalPendingError

# 1. Load, validate, and freeze the contract
enforcer = ContractEnforcer.load("implementations/n8n/duplicate-issue-detector/contract.yaml")

# 2. Gate sensitive tools and operations
@enforcer.gate(action_name="github: issues:write", action_type="permission")
def post_github_comment(issue_id: int, comment: str):
    print(f"Posting comment to issue #{issue_id}: {comment}")
    return True

@enforcer.gate(action_name="aws_s3:read", action_type="permission")
def read_s3_bucket():
    return "s3_data"

# 3. Allowed calls execute cleanly and log to audit trail
post_github_comment(101, "Potential duplicate detected.")

# 4. Undeclared actions are denied immediately (Default-Deny)
try:
    read_s3_bucket()
except ContractViolationError as e:
    print(f"Blocked by Scyvera: {e}")

# 5. Inspect the immutable audit log
for entry in enforcer.get_audit_log():
    print(f"[{entry.timestamp}] {entry.decision} - {entry.action_name} ({entry.reason})")

# 6. Verify file integrity on disk (Threat T5 defense)
enforcer.verify_integrity()  # Raises ContractTamperError if contract.yaml was modified
```

---

## ⚠️ What Scyvera Does Not Guarantee

Scyvera provides structural verification and runtime gating, but security is an end-to-end discipline. Integrators must understand the following technical boundaries:

1. **Gate Bypass (Threat T4)**: Scyvera enforces boundaries at the `@enforcer.gate(...)` decorator. In Python, the runtime cannot physically prevent code from directly calling an un-decorated internal function. Integrators should use `ContractEnforcer.assert_gated(fn)` within their integration test suites to verify that all external-facing tool call sites are wrapped.
2. **Internal Third-Party Behavior / String Spoofing (Threat T6)**: Scyvera verifies that a declared intent (e.g. `github:issues:write`) matches an allowed permission in the contract. It does not perform dynamic bytecode analysis or network-packet inspection to guarantee that a decorated library function does not execute unauthorized background calls. The integrity of third-party dependencies remains the responsibility of dependency scanning and peer review.
3. **Pre-Load File Tampering (Threat T5)**: The SHA-256 integrity check in `verify_integrity()` protects against file replacement AFTER load. It does not protect against a tampered `contract.yaml` being present BEFORE `ContractEnforcer.load()` is called. The deployment environment is responsible for protecting the contract file prior to load.

---

You can programmatically construct, inspect, serialize, and validate Agent Contracts in Python without manually writing YAML:

```python
from scyvera import Contract, validate_contract

# Programmatically construct a v1.1 Contract
contract = (
    Contract(name="Literature Research Assistant", purpose="Analyzes scientific papers")
    .set_domain("research")
    .add_capability("search_documents", description="Queries research repositories")
    .add_resource("paper_db", type="pdf_repository", access="read")
    .add_input("research_topic", type="string", required=True)
    .add_output("summary", type="document")
    .add_permission("paper_db", actions=["read", "search"])
    .set_state("session")
    .set_recovery("retry")
    .set_replay("idempotent")
    .set_observability("basic")
    .set_risk("low", category="misinformation_risk")
)

# Validate directly in code
result = contract.validate()

if result.valid:
    print("Contract is valid!")
    # Save to file
    contract.save("contract.yaml")
else:
    for err in result.errors:
        print(f"Error at {err.path}: {err.message}")
```

Validate an existing YAML file programmatically:
```python
from scyvera import validate_contract

result = validate_contract("contract.yaml")
print(f"Valid: {result.valid}")
```

---

## 📋 Every Implementation Documents a Contract

Instead of prose documentation alone, systems in this repository specify:

- **Identity & Purpose** — system identity, operational scope, and system version
- **Capabilities** — semantic ability claims
- **Resources** — data stores, APIs, entities, or systems accessed
- **Inputs & Outputs** — data entering and produced by the system
- **Permissions** — exact authorized `{resource, actions[]}` combinations
- **Constraints** — quantitative limits (e.g. rate limits, transaction caps)
- **Side Effects** — externally observable mutations
- **Approvals** — explicit human or expert approval gates
- **Dependencies** — required external services, models, APIs
- **State, Recovery, Replay, Observability** — persistence, failure strategy, idempotency, and audit evidence
- **Artifact Security & Risk** — model/data artifact trust requirements and risk level classification

---

## 📂 Repository Structure

```text
agent-contracts/
├── README.md
├── WORKFLOW-CONTRACT-SPEC.md
├── CONTRIBUTING.md
├── CONTRIBUTORS.md
├── LICENSE
├── pyproject.toml
├── docs/
│   ├── contract-model-v1.1.md          # Normative v1.1 Specification
│   ├── vision.md                       # Strategic Project Vision
│   ├── design-principles.md            # Normative Design Principles
│   └── terminology.md                  # Specification Terminology
├── schemas/
│   ├── v1/                             # Contract v1 JSON Schema
│   │   └── contract.schema.json
│   └── v1.1/                           # Contract v1.1 JSON Schema
│       └── contract.schema.json
├── examples/
│   └── v1.1/                           # Domain-Neutral Examples (v1.1)
│       ├── education-tutor.yaml
│       ├── research-assistant.yaml
│       ├── financial-operations.yaml
│       └── clinical-information-assistant.yaml
├── src/
│   └── scyvera/                # Python Package
│       ├── __init__.py
│       ├── builder.py                  # Programmatic Contract Builder API
│       ├── validator.py                # Multi-Version Validator Engine
│       ├── cli.py                      # CLI Application (validate, init)
│       └── schemas/                    # Bundled Package Schemas
├── tests/
│   ├── fixtures/                       # Test Fixture Files
│   ├── test_validator.py              # v1 Validator Unit Tests
│   ├── test_validator_v1_1.py         # v1.1 Validator Unit Tests
│   ├── test_builder.py                # Programmatic Builder Unit Tests
│   └── test_cli.py                    # CLI Unit Tests
└── implementations/                    # Multi-Framework Reference Implementations
    ├── n8n/
    └── langgraph/
```

---

## 🌐 Domain-Neutral Example Contracts (v1.1)

See [`examples/v1.1/`](./examples/v1.1) for runnable, validated v1.1 contracts across different domains:

| Domain | Contract File | Description |
|---|---|---|
| **Education** | [`education-tutor.yaml`](./examples/v1.1/education-tutor.yaml) | Guided study tutor, low risk, session state |
| **Research** | [`research-assistant.yaml`](./examples/v1.1/research-assistant.yaml) | Scientific literature analysis, arXiv API dependency |
| **Finance** | [`financial-operations.yaml`](./examples/v1.1/financial-operations.yaml) | Critical risk, payment caps ($5000 USD limit), controller approval gate |
| **Healthcare** | [`clinical-information-assistant.yaml`](./examples/v1.1/clinical-information-assistant.yaml) | High risk, EHR database access, physician approval gate, model integrity requirements |

---

## 🔐 Security & Governance Boundary Notice

> [!IMPORTANT]
> **Contract Declaration ≠ Security Verification ≠ Runtime Enforcement.**
> An Agent Contract describes declared operational boundaries. It is not a sandbox, anti-malware scanner, or runtime enforcement proxy. Contract declarations provide structured input upon which external policy engines, verification scanners, and runtime isolation systems operate.

---

## 🗺️ Where the Spec Is Headed (v1.1)

Contract v1 was designed and proven against coding/developer agents. That's now understood to be a starting substrate, not the ceiling — v1.1 is a deliberate audit-and-redesign effort to make the spec:

- **Domain-independent** — usable for research, education, finance, business-workflow, and healthcare-workflow agents, not just coding agents
- **Framework-independent** — already true in principle (n8n + LangGraph prove it), being stress-tested further
- **Accessible to non-technical authors** — YAML/JSON is a representation format, not meant to be the only way to create a contract

This is genuinely in the design/audit phase — classifying existing Contract v1 fields, testing them against non-coding agent archetypes, and only then extending the schema. Nothing in this section describes a shipped feature. Follow progress in [`implementations/rfcs/`](./implementations/rfcs) and open issues tagged `v1.1`.

---

## 🤝 Contributing

Contributions are welcome — new domain profiles, framework reference implementations, specification RFCs, or Python API improvements. See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.

---

## 📄 License

Distributed under the MIT License — see [LICENSE](./LICENSE) for details.

Built and maintained by [Shinjan Das](https://github.com/Skull-boy) and open-source contributors — see [CONTRIBUTORS.md](./CONTRIBUTORS.md).
