Metadata-Version: 2.4
Name: sayfos-sdk
Version: 0.1.0
Summary: Sayfos Protocol — Agent Runtime Control Protocol
Author-email: SAYFOS <278927879@qq.com>
License: Apache-2.0
Keywords: ai-safety,agent-security,intent-verification,causal-consistency,budget-governance,source-chain
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2.0; extra == "langchain"
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == "api"
Requires-Dist: uvicorn>=0.29; extra == "api"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# Sayfos SDK

Sayfos SDK is a lightweight community SDK for agent runtime control.

It provides reference data objects, verification hooks, and framework adapters
for checking automated actions before they reach tools, APIs, data systems,
cloud resources, or embodied endpoints.

This repository is a community reference implementation, not the full
enterprise gateway or managed control plane.

## What Sayfos Helps With

Automated execution agents often need to answer three questions before a
high-risk action is allowed:

1. Does the action have a verifiable source chain?
2. Is the action still within its delegated budget and runtime authority?
3. Does the digital action have enough contextual or embodied evidence?

Sayfos SDK exposes common objects and lightweight reference engines for those
checks so developers can add runtime guardrails around AI agents, RPA systems,
workflow engines, coding agents, cloud-operation agents, robots, vehicle
agents, and IoT agents.

## Installation

```bash
pip install sayfos-sdk
```

With the LangChain adapter:

```bash
pip install sayfos-sdk[langchain]
```

With the development API server:

```bash
pip install sayfos-sdk[api]
```

## Quick Start

```python
from sayfos import (
    ActionDeclaration,
    IntentVerificationRequest,
    SayfosPipeline,
    Verdict,
)

declaration = ActionDeclaration(
    actor_type="langchain_tool",
    action_type="send_payment",
    target="acct_42",
    parameters={"amount": 150.0, "currency": "CNY"},
    root_authorization_ref="auth://user/alice",
    task_lineage_ref="task://report/step-3",
    risk_level=5,
)

request = IntentVerificationRequest(
    action=declaration,
    touch_events=12,
    screen_on=True,
    device_held=True,
    budget_remaining={"amount": 500.0, "tool_calls": 10},
)

pipeline = SayfosPipeline()
token = pipeline.evaluate(request)

if token.verdict != Verdict.ALLOW:
    raise RuntimeError(f"Blocked: {token.reason_code}")

result = execute_payment(**declaration.parameters)
```

## Standard Objects

The community SDK centers on a small set of machine-readable objects:

| Object | Role |
| --- | --- |
| ActionDeclaration | Proposed automated action |
| IntentVerificationRequest | Action plus runtime evidence |
| EmbodiedResponse | Contextual or embodied consistency result |
| Budget | Delegated runtime authority and quotas |
| PreflightPlan | Multi-step execution plan |
| ExecutionBoundary | Machine-readable plan or step boundary |
| AdjudicationToken | Binding verdict and constraints |
| AuditSummary | Machine-verifiable audit summary |

## Reference Verification Dimensions

| Dimension | What it checks |
| --- | --- |
| Source-chain integrity | Whether the action carries required provenance references |
| Budget governance | Whether the action is within delegated runtime authority |
| Plan preflight | Whether a multi-step plan stays within execution boundaries |
| Embodied consistency | Whether digital action evidence matches contextual or physical evidence |

The bundled engines are intentionally lightweight. Production deployments
should use durable storage, authenticated policy management, operational
monitoring, and stronger organization-specific decision logic.

## LangChain Adapter

```python
from sayfos.adapters.langchain import SayfosLangChainInterceptor, BlockedActionError

interceptor = SayfosLangChainInterceptor()

@interceptor.guard
@tool
def transfer_funds(amount: float, to: str) -> str:
    return f"Transferred {amount} to {to}"

try:
    transfer_funds(100.0, "acct_evil")
except BlockedActionError as e:
    print(f"Blocked: {e.token.reason_code}")
```

## CLI

```bash
sayfos verify --action '{"action_type":"payment","parameters":{"amount":100}}'
sayfos budget create --owner agent-1 --quotas '{"amount_cny":5000}'
sayfos plan preflight --plan '{"steps":[]}' --budget-id <budget-id>
```

## Open Source Boundary

This repository provides public interfaces, reference objects, lightweight
verification engines, examples, and adapters under Apache 2.0.

Enterprise gateway capabilities, managed policy engines, certification
services, production control planes, and commercial support are separate
offerings and are not provided by this community SDK.

## Notices

See LICENSE for the Apache 2.0 license.

See PATENT_NOTICE.md and TRADEMARK.md for additional patent and trademark
notices related to this project.
