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.

---

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

---

🛡️ Governance & Enforcement Layers

Scyvera provides three 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
Gateway Enforcement	BaseGateway, GitHubGateway, QdrantGateway	Single enforcement boundary: holds credentials privately and gates every third-party API call, structurally preventing gate bypass.	Credential & API isolation

---

⚡ Quickstart

1. Installation

Install the core package from PyPI:

pip install scyvera

Or install with optional gateway dependencies:

# With PyGithub for GitHubGateway
pip install "scyvera[github]"

# With qdrant-client for QdrantGateway
pip install "scyvera[qdrant]"

# With all gateway adapters
pip install "scyvera[all]"

# For local development:
pip install -e ".[dev]"

2. Command-Line Interface (CLI)

Create a starter Contract template (v1.1)

scyvera init contract.yaml --name "Research Assistant"

Interactive wizard mode:

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:

scyvera validate contract.yaml

Output:

PASS  contract.yaml

Override with a custom JSON Schema file:

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.

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

---

🚪 Gateway Enforcement Architecture (v1.1.3)

In automated agent workflows, security boundaries fail if agent nodes can bypass enforcers by importing and calling API clients directly. Scyvera solves this with Gateways (BaseGateway, GitHubGateway, QdrantGateway):

• Single Enforcement Boundary: API credentials and raw SDK clients (e.g. PyGithub, qdrant-client) are encapsulated privately within the gateway. No outside node holds credentials or raw clients.
• Structural Gating: Every public method is decorated per-instance with @enforcer.gate(...). Any undeclared or unapproved action halts execution immediately via ContractViolationError or ApprovalPendingError.
• Exception Normalization: Client exceptions are caught and wrapped into GatewayError to ensure deterministic fault isolation.

from scyvera import ContractEnforcer, GitHubGateway, GatewayError, ContractViolationError

# 1. Load the contract enforcer
enforcer = ContractEnforcer.load("contract.yaml")

# 2. Instantiate gateway with injected enforcer and private credentials
gateway = GitHubGateway(enforcer, token="ghp_...")

# 3. Gated read operation (succeeds if declared in contract)
issue = gateway.read_issue("owner/repo", issue_number=42)

# 4. Gated mutating operation (enforces Default-Deny & approvals)
try:
    gateway.close_issue("owner/repo", issue_number=42)
except ContractViolationError as e:
    print(f"Blocked by Scyvera: {e}")

---

⚠️ What Scyvera Does Not Guarantee

Scyvera provides structural verification, runtime gating, and gateway isolation, 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. To eliminate the risk of ungated bypass, applications should use Scyvera Gateways (BaseGateway, GitHubGateway, QdrantGateway), where credentials and raw SDK clients are kept strictly private inside the gateway. If invoking ungated custom functions directly, integrators should use ContractEnforcer.assert_gated(fn) in test suites.
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:

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:

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

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
│       ├── enforcer.py                 # Runtime Contract Enforcer
│       ├── gateway.py                  # Gateway Enforcement Layer (GitHub, Qdrant)
│       ├── exceptions.py               # Exception Hierarchy
│       ├── linter.py                   # Semantic Contract Linter
│       ├── cli.py                      # CLI Application (validate, init, lint)
│       └── schemas/                    # Bundled Package Schemas
├── tests/
│   ├── fixtures/                       # Test Fixture Files
│   ├── test_builder.py                # Programmatic Builder Unit Tests
│   ├── test_cli.py                    # CLI Unit Tests
│   ├── test_duplicate_issue_detector_workflow.py # Workflow Embedding Tests
│   ├── test_enforcer.py               # Runtime Enforcer Tests (T1-T10)
│   ├── test_filename_enforcement.py   # Filename Rule Tests (.yaml only)
│   ├── test_gateway.py                # Gateway Enforcement Tests
│   ├── test_lifecycle.py              # Lifecycle Validation Tests
│   ├── test_linter.py                 # Semantic Linter Tests
│   ├── test_schemas_sync.py           # Schema Synchronization Tests
│   ├── test_validator.py              # v1 Validator Unit Tests
│   └── test_validator_v1_1.py         # v1.1 Validator Unit Tests
└── implementations/                    # Multi-Framework Reference Implementations
    ├── n8n/
    └── langgraph/

---

🌐 Domain-Neutral Example Contracts (v1.1)

See examples/v1.1/ for runnable, validated v1.1 contracts across different domains:

Domain	Contract File	Description
Education	education-tutor.yaml	Guided study tutor, low risk, session state
Research	research-assistant.yaml	Scientific literature analysis, arXiv API dependency
Finance	financial-operations.yaml	Critical risk, payment caps ($5000 USD limit), controller approval gate
Healthcare	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/ 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 for details.

---

📄 License

Distributed under the MIT License — see LICENSE for details.

Built and maintained by Shinjan Das and open-source contributors — see CONTRIBUTORS.md.