Metadata-Version: 2.4
Name: openagent-oas
Version: 1.0.0
Summary: Python SDK for the Open Agent Specification (OAS) — decentralized identity for autonomous entities
Project-URL: Homepage, https://openagent.id
Project-URL: Repository, https://github.com/OpenAgentID/oas
Project-URL: Specification, https://openagent.id/standards/oas
Author-email: "L1fe Labs, Inc." <oss@l1fe.ai>
License: MIT
License-File: LICENSE
Keywords: agent,decentralized,did,identity,oas
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: blake3>=1.0
Requires-Dist: cryptography>=43.0
Provides-Extra: dev
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# openagent-oas

Python SDK for the [Open Agent Specification (OAS)](https://openagent.id/standards/oas) -- decentralized identity for autonomous entities.

`openagent-oas` implements the `did:oas` DID method, Ed25519 cryptographic lineage, document management, verifiable credential attestation, and DID resolution. It provides everything needed to create, derive, sign, verify, and resolve identities in the OAS ecosystem.

No network required. No blockchain required. No vendor lock-in.

```python
from openagent.oas.sdk import create_hmr, derive_child, verify_chain
from openagent.oas.did import EntityKind
from openagent.oas.lineage import InMemoryProvider

# Create a Human Root identity
hmr = create_hmr("l1fe", "root", "2025-01-01T00:00:00Z")
print(hmr.document.id)  # did:oas:l1fe:hmr:root

# Derive an agent identity
agent = derive_child(
    parent_keypair=hmr.keypair,
    parent_document=hmr.document,
    namespace="l1fe",
    kind=EntityKind.AGENT,
    identifier="analyzer",
    derivation_path="agent/analyzer",
    created="2025-01-01T00:00:00Z",
)
print(agent.document.id)  # did:oas:l1fe:agent:analyzer

# Verify the lineage chain
provider = InMemoryProvider()
provider.add(hmr.document)
provider.add(agent.document)
await verify_chain(agent.document, provider)
```

## Installation

```bash
pip install openagent-oas
```

Requires **Python >= 3.12**. Runtime dependencies: `cryptography>=43.0`, `blake3>=1.0`.

```bash
# With development dependencies
pip install openagent-oas[dev]
```

## Package Structure

```
openagent.oas
  |-- did          DID parsing, validation, and EntityKind enumeration
  |-- crypto       Ed25519 keypairs, HKDF derivation, BLAKE3, lineage proofs, encoding
  |-- document     OAS document construction, signing, and conformance levels
  |-- lineage      Child entity derivation and lineage chain verification
  |-- resolve      DID resolution with in-memory, caching, and fallback resolvers
  |-- attestation  W3C Verifiable Credential signing and verification
  |-- sdk          High-level convenience API combining all modules
```

## Type Checking

This package is PEP 561 compliant (`py.typed` marker included). All public APIs are fully annotated for use with mypy strict mode:

```bash
mypy --strict your_project/
```

---

## Complete API Reference

### `openagent.oas.did` -- DID Parsing and Validation

DID parsing, validation, and entity kind classification for the `did:oas` method. A `did:oas` DID has the form `did:oas:<namespace>:<kind>:<identifier>`.

```python
from openagent.oas.did import (
    OasDid, EntityKind,
    validate_namespace, validate_identifier,
    DidError, DidParseError, InvalidNamespaceError,
    InvalidIdentifierError, UnknownEntityKindError,
)
```

**`OasDid`** -- frozen dataclass (`namespace: str`, `kind: EntityKind`, `identifier: str`)

| Method / Property | Signature | Description |
|---|---|---|
| `parse` | `@classmethod parse(input_str: str) -> OasDid` | Parse a `did:oas:...` string |
| `is_root` | `@property -> bool` | True if kind is HMR, MHR, or ENR |
| `__str__` | `() -> str` | `did:oas:<namespace>:<kind>:<identifier>` |

**`EntityKind`** -- `str` enum: `HMR`, `MHR`, `ENR`, `AO`, `AGENT`, `AGENT_INSTANCE`, `TOOL`, `SKILL`, `WORKFLOW`, `MODEL`, `DATASET`, `SERVICE`

| Method | Signature | Description |
|---|---|---|
| `is_root` | `() -> bool` | True if HMR, MHR, or ENR |
| `component_count` | `() -> int` | Colon-separated component count |
| `from_string` | `@classmethod (value: str) -> EntityKind` | Parse string to EntityKind |

**Functions:**

| Function | Signature |
|---|---|
| `validate_namespace` | `(namespace: str) -> str` |
| `validate_identifier` | `(identifier: str) -> str` |

**Exceptions:** `DidError` (base), `DidParseError`, `InvalidNamespaceError`, `InvalidIdentifierError`, `UnknownEntityKindError`

---

### `openagent.oas.crypto` -- Cryptographic Operations

Ed25519 keypairs, HKDF-SHA256 derivation, BLAKE3 hashing, lineage proofs, JCS canonicalization, and encoding utilities.

```python
from openagent.oas.crypto import (
    OasKeyPair, derive_child_keypair, derive_key_material,
    AgentLineageProof, blake3_hash, canonicalize,
    base58_encode, base58_decode, base64url_encode, base64url_decode,
    multibase_encode, multibase_decode,
    CryptoError, KeyGenerationError, SignatureError,
    DerivationError, ProofError, EncodingError,
)
```

**`OasKeyPair`** -- Ed25519 keypair. Private keys never appear in `__repr__`.

| Method / Property | Signature | Description |
|---|---|---|
| `generate` | `@classmethod () -> OasKeyPair` | New keypair via CSPRNG |
| `from_signing_key_bytes` | `@classmethod (key_bytes: bytes) -> OasKeyPair` | Restore from 32-byte seed |
| `sign` | `(message: bytes) -> bytes` | 64-byte Ed25519 signature |
| `verify_with_key` | `@staticmethod (public_key: bytes, message: bytes, signature: bytes) -> None` | Verify signature |
| `verifying_key_bytes` | `@property -> bytes` | 32-byte public key |
| `signing_key_bytes` | `@property -> bytes` | 32-byte private key seed |
| `public_key_multibase` | `@property -> str` | `z` + base58btc encoded public key |
| `public_keys_equal` | `(other: OasKeyPair) -> bool` | Constant-time comparison |

**`AgentLineageProof`** -- frozen dataclass (`type`, `parent_did`, `child_did`, `derivation_path`, `algorithm`, `public_key_multibase`, `signature`)

| Method | Signature |
|---|---|
| `generate` | `@classmethod (*, parent_keypair: OasKeyPair, parent_did: str, child_did: str, derivation_path: str) -> AgentLineageProof` |
| `verify` | `() -> None` |
| `verify_with_key` | `(parent_public_key: bytes) -> None` |
| `to_dict` | `() -> dict[str, str]` |
| `from_dict` | `@classmethod (data: dict[str, str]) -> AgentLineageProof` |

**Functions:**

| Function | Signature |
|---|---|
| `derive_child_keypair` | `(parent: OasKeyPair, path: str) -> OasKeyPair` |
| `derive_key_material` | `(ikm: bytes, salt: bytes, info: str) -> bytes` |
| `blake3_hash` | `(data: bytes) -> bytes` |
| `canonicalize` | `(value: Any) -> bytes` |
| `base58_encode` | `(data: bytes) -> str` |
| `base58_decode` | `(encoded: str) -> bytes` |
| `base64url_encode` | `(data: bytes) -> str` |
| `base64url_decode` | `(encoded: str) -> bytes` |
| `multibase_encode` | `(data: bytes) -> str` |
| `multibase_decode` | `(encoded: str) -> bytes` |

**Exceptions:** `CryptoError` (base), `KeyGenerationError`, `SignatureError`, `DerivationError`, `ProofError`, `EncodingError`

---

### `openagent.oas.document` -- Document Construction and Signing

OAS document construction via fluent builder, signing, proof generation, and conformance levels.

```python
from openagent.oas.document import (
    OasDocument, DocumentMetadata, DocumentBuilder,
    ConformanceLevel, LifecycleStatus, VerificationMethod,
    ServiceEndpoint, LineageSection, DocumentProof,
    DocumentError, DocumentBuildError,
    DocumentValidationError, DocumentProofError,
)
```

**`OasDocument`** -- frozen dataclass (`id`, `kind`, `conformance_level`, `verification_method`, `authentication`, `metadata`, `lineage`, `proof`, `service`)

**`DocumentBuilder`** -- fluent builder

| Method | Signature |
|---|---|
| `__init__` | `(*, did: str, kind: str) -> None` |
| `conformance_level` | `(level: ConformanceLevel) -> DocumentBuilder` |
| `add_verification_method` | `(vm: VerificationMethod) -> DocumentBuilder` |
| `add_service` | `(service: ServiceEndpoint) -> DocumentBuilder` |
| `lineage` | `(section: LineageSection) -> DocumentBuilder` |
| `build_and_sign` | `(*, keypair: OasKeyPair, created: str) -> OasDocument` |

**Enums:** `ConformanceLevel` (`L0`, `L1`, `L2`), `LifecycleStatus` (`NASCENT`, `ACTIVE`, `DORMANT`, `SUSPENDED`, `TERMINATED`, `ARCHIVED`)

**Data types:** `VerificationMethod`, `ServiceEndpoint`, `LineageSection`, `DocumentProof`, `DocumentMetadata` -- all frozen dataclasses with `to_dict()` and `from_dict()` methods.

**`DocumentProof`** additional methods:

| Method | Signature |
|---|---|
| `verify` | `(document_json: dict[str, Any], public_key_bytes: bytes) -> None` |
| `create_and_sign` | `@classmethod (*, document_dict: dict[str, Any], keypair: OasKeyPair, verification_method_id: str, created: str) -> DocumentProof` |

**Exceptions:** `DocumentError` (base), `DocumentBuildError`, `DocumentValidationError`, `DocumentProofError`

---

### `openagent.oas.lineage` -- Lineage Derivation and Verification

Child entity derivation and multi-hop lineage chain verification.

```python
from openagent.oas.lineage import (
    derive_child_entity, DerivedEntity,
    verify_lineage, verify_lineage_structural,
    VerifyConfig, DocumentProvider, InMemoryProvider,
    LineageError, ParentMismatchError, SignatureInvalidError,
    ChainTooDeepError, ResolutionError, LineageStructuralError,
)
```

**Functions:**

| Function | Signature |
|---|---|
| `derive_child_entity` | `(*, parent_keypair: OasKeyPair, parent_document: OasDocument, namespace: str, kind: EntityKind, identifier: str, derivation_path: str, created: str) -> DerivedEntity` |
| `verify_lineage` | `async (document: OasDocument, provider: DocumentProvider, config: VerifyConfig \| None = None) -> None` |
| `verify_lineage_structural` | `(document: OasDocument) -> None` |

**`DerivedEntity`** -- frozen dataclass (`document: OasDocument`, `keypair: OasKeyPair`)

**`VerifyConfig`** -- frozen dataclass (`max_generations: int = 16`, `verify_signatures: bool = True`)

**`DocumentProvider`** -- Protocol with `async def resolve(self, did: str) -> OasDocument`

**`InMemoryProvider`** -- `add(document)`, `async resolve(did)`

**Exceptions:** `LineageError` (base), `ParentMismatchError`, `SignatureInvalidError`, `ChainTooDeepError`, `ResolutionError`, `LineageStructuralError`

---

### `openagent.oas.resolve` -- DID Resolution

Pluggable DID resolution with in-memory, caching, and fallback implementations.

```python
from openagent.oas.resolve import (
    Resolver, InMemoryResolver, CachingResolver, FallbackResolver,
    ResolveError, DidNotFoundError, ResolverChainExhaustedError,
)
```

**`Resolver`** -- Protocol with `async def resolve(self, did: str) -> OasDocument`

**`InMemoryResolver`** -- `add(document)`, `add_many(documents)`, `async resolve(did)`, `contains(did)`, `count()`

**`CachingResolver`** -- `__init__(inner, ttl_seconds=300)`, `async resolve(did)`, `invalidate(did)`, `clear()`, `cache_size()`

**`FallbackResolver`** -- `__init__(resolvers: list[object])`, `async resolve(did)`

**Exceptions:** `ResolveError` (base), `DidNotFoundError`, `ResolverChainExhaustedError`

---

### `openagent.oas.attestation` -- Verifiable Credentials

W3C Verifiable Credential signing and verification for OAS entity attestation.

```python
from openagent.oas.attestation import (
    OasCredential, CredentialSubject, AttestationType,
    sign_credential, verify_credential,
    AttestationError, CredentialBuildError,
    CredentialSignError, CredentialVerifyError,
)
```

**`OasCredential`** -- frozen dataclass (`context`, `type`, `issuer`, `issuance_date`, `credential_subject`, `proof`)

**`CredentialSubject`** -- frozen dataclass (`id`, `type: AttestationType`, `claims`)

**`AttestationType`** -- `str` enum: `IDENTITY`, `CAPABILITY`, `COMPLIANCE`, `TRUST`, `CLASSIFICATION`, `PROVENANCE`

| Function | Signature |
|---|---|
| `sign_credential` | `(credential: OasCredential, keypair: OasKeyPair, verification_method_id: str, created: str) -> OasCredential` |
| `verify_credential` | `(credential: OasCredential, public_key_bytes: bytes) -> None` |

**Exceptions:** `AttestationError` (base), `CredentialBuildError`, `CredentialSignError`, `CredentialVerifyError`

---

### `openagent.oas.sdk` -- High-Level Convenience API

Unified entry points combining all modules.

```python
from openagent.oas.sdk import (
    create_hmr, create_mhr, create_root_with_keypair,
    derive_child, verify_chain, CreatedIdentity, OasError,
)
```

| Function | Signature |
|---|---|
| `create_hmr` | `(namespace: str, identifier: str, created: str) -> CreatedIdentity` |
| `create_mhr` | `(namespace: str, identifier: str, created: str) -> CreatedIdentity` |
| `create_root_with_keypair` | `(*, namespace: str, kind: EntityKind, identifier: str, keypair: OasKeyPair, created: str) -> OasDocument` |
| `derive_child` | `(*, parent_keypair: OasKeyPair, parent_document: OasDocument, namespace: str, kind: EntityKind, identifier: str, derivation_path: str, created: str) -> DerivedEntity` |
| `verify_chain` | `async (document: OasDocument, provider: DocumentProvider, config: VerifyConfig \| None = None) -> None` |

**`CreatedIdentity`** -- frozen dataclass (`document: OasDocument`, `keypair: OasKeyPair`)

**`OasError`** -- `__init__(*, message: str, cause: Exception | None = None)`, unified SDK-level exception wrapping all sub-module errors.

---

## Development

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

pytest                     # Run tests
mypy --strict .            # Type checking
ruff check .               # Lint
ruff format --check .      # Format check
```

## Cross-Language SDKs

OAS is implemented across multiple languages with full specification parity:

| Language | Package | Install |
|----------|---------|---------|
| **Rust** (reference) | `oas-sdk` | `cargo add oas-sdk` |
| **TypeScript** | `@openagentid/oas-sdk` | `npm install @openagentid/oas-sdk` |
| **Go** | `github.com/openagentid/oas-go` | `go get github.com/openagentid/oas-go` |
| **Python** | `openagent-oas` | `pip install openagent-oas` |
| **Swift** | `oas-swift` | SPM package dependency |
| **Kotlin** | `id.openagent.oas:oas-sdk` | Gradle/Maven dependency |
| **Vanilla JS** | `@openagentid/oas-vanilla` | Zero-dependency, browser-native |

## License

Copyright © 2026 [L1fe Labs, Inc.](https://l1fe.ai)

Licensed under the [MIT license](LICENSE).
