Metadata-Version: 2.4
Name: twin3-sdk
Version: 0.2.10a0
Summary: The Universal Capability Motherboard for Autonomous AI Agents and Self-Sovereign Humans
Author-email: Twin3 AI Limited <core@twin3.ai>
License-Expression: LicenseRef-Twin3-Proprietary
Project-URL: Homepage, https://github.com/twin3-team/twin3-sdk
Project-URL: Repository, https://github.com/twin3-team/twin3-sdk.git
Project-URL: Documentation, https://github.com/twin3-team/twin3-sdk/blob/main/README.md
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

# Twin3 SDK (`twin3-sdk`)
> **The Universal Capability Motherboard for Autonomous AI Agents & Self-Sovereign Humans**

[English](README.md) | [繁體中文](README_ZH.md) | [GitHub: twin3-team/twin3-sdk](https://github.com/twin3-team/twin3-sdk)

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
[![Architecture: 7-Layer Symbiosis](https://img.shields.io/badge/Architecture-7--Layer%20Symbiosis-success.svg)](#the-seven-layer-symbiotic-architecture)
[![Dual-Projection](https://img.shields.io/badge/Dual--Use-Agent%20ID%20%7C%20Human%20ID-orange.svg)](#dual-application-projections)
[![Repo: twin3-team/twin3-sdk](https://img.shields.io/badge/GitHub-twin3--team%2Ftwin3--sdk-purple.svg)](https://github.com/twin3-team/twin3-sdk)

---

## 1. Overview & Vision

**Twin3 SDK** is a domain-agnostic, cryptographically secure foundational runtime designed to bridge autonomous AI agents and self-sovereign human individuals into a single symbiotic economic network.

As AI models evolve toward fully autonomous trading actors, the primary barrier to adoption is not intelligence, but **counterparty trust, deterministic authorization, cryptographic non-repudiation, and autonomous financial settlement**.

Twin3 SDK solves this by establishing a **Seven-Layer Symbiotic Architecture (L1 to L7)**. It serves as the universal hardware-like motherboard, while domain-specific applications plug into it as specialized software projections:
1. **Agent ID (Enterprise Projection)**: Powers B2B autonomous commerce, procurement negotiation, and Dun & Bradstreet (D-U-N-S) enterprise identity verification across 20 commercial capabilities.
2. **Human ID (Sovereign Projection)**: Protects 140,000+ real-world human identity assets, providing Passkey (WebAuthn) biometrics, personal sovereign cards, and paid anti-spam inboxes.

---

## 2. The Seven-Layer Symbiotic Architecture

Twin3 SDK organizes all distributed primitives into seven clean, composable layers:

```
                  ┌─────────────────────────────────────────────────────────┐
                  │                 Twin3 SDK Core Engine                   │
                  ├────┬───────────────────────┬────────────────────────────┤
                  │ L1 │ Discovery Layer       │ twin3.discovery            │
                  │ L2 │ Trust & Identity      │ twin3.trust                │
                  │ L3 │ Communication Layer   │ twin3.comm                 │
                  │ L4 │ Shield & Guardrails   │ twin3.shield               │
                  │ L5 │ Matrix Understanding  │ twin3.matrix               │
                  │ L6 │ Clearing & Settlement │ twin3.settlement           │
                  │ L7 │ Governance & Audit    │ twin3.governance           │
                  └────┴───────────────────────┴────────────────────────────┘
                               ▲                             ▲
                               │                             │
          ┌────────────────────┴───────────┐    ┌────────────┴─────────────────┐
          │     Agent ID (Enterprise)      │    │      Human ID (Sovereign)    │
          ├────────────────────────────────┤    ├──────────────────────────────┤
          │ • A2A 5-Stage Commercial Loop  │    │ • Sovereign Identity Card    │
          │ • D-U-N-S Entity Verification  │    │ • 140,000 Personality Vectors│
          │ • Manufacturing Tolerance Match│    │ • Passkey WebAuthn Login     │
          │ • Corporate Multi-Sig Escrow   │    │ • Paid Threshold Inbox       │
          └────────────────────────────────┘    └──────────────────────────────┘
```

### Layer Breakdown

| Layer | Module Path | Purpose | Key Primitives & Protocols |
| :--- | :--- | :--- | :--- |
| **L1 Discovery** | `twin3.discovery` | Agent Card & Sovereign Card specifications, public inbox declaration, in-memory registry. | `AgentCard`, `SovereignCard`, `build_declaration`, `DiscoveryRegistry` |
| **L2 Trust** | `twin3.trust` | Cryptographic identity handshake, public/private key verification, authority anchoring. | `create_challenge` / `complete_challenge` / `verify_binding`, `PasskeyAdapter`, `AuthorityAnchor`, `resolve_did_web`, nonce and sign-count stores |
| **L3 Communication** | `twin3.comm` | Non-repudiable message packaging, counterparty attention ladder, task inbox. | `build_envelope` / `validate_envelope` (Ed25519), `CounterpartyTable`, `TaskInbox`, owner access grants |
| **L4 Shield** | `twin3.shield` | Differential tampering defense, prompt injection filtering, and authorization guardrails. | `scan_text` / `scan_envelope` (T0–T3), `IntelEngine` (T1), `Ensemble` (T4), `diff_plans` / `authorize_execution` (T5), `MemoryGuard` |
| **L5 Matrix** | `twin3.matrix` | High-density vector space topological mapping and semantic cosine matching. | `DenseVector256`, `feature_distance`, `HumanMatrixSchema`, `EnterpriseMatrixSchema` |
| **L6 Settlement** | `twin3.settlement` | Signed-receipt verification for HTTP 402 gates, with externally supplied chain-finality and replay controls. | `PaymentDemand`, `PaymentReceipt`, `X402SettlementEngine` |
| **L7 Governance** | `twin3.governance` | Immutable evidence trail, appeals, advisory reputation federation, provisional arbitration helper. | `EvidenceTrail`, `open_appeal` / `resolve_appeal`, `export_reputation` / `import_reputation`, `ArbitrationEngine` (experimental), `DisputeCase` (experimental) |

`(experimental)` marks a capability whose row in [`tests/capability-inventory.json`](tests/capability-inventory.json) is not yet `available`: it is importable today and its surface may still change. Everything unmarked is `available`. A name written `Class.method` is a method, not a module export. Every name in this table is checked against a real public export by [`tests/test_readme_capability_claims.py`](tests/test_readme_capability_claims.py).

---

## 3. Pull Request Lineage & Provenance

The primitives in `twin3-sdk` are extracted from the `twin3-team/agent-id` Inbox line (PRs #615–#642, merged 2026-09-03 → 2026-09-05; spec: `docs/architecture/inbox-module-spec.md` in that repo). What each layer inherited:

* **Envelope, KYA handshake, counterparty ladder** — `agent_id/inbox/{envelope,kya,counterparty}.py`: canonical-JSON signed envelopes with `authority:"none"`, the mutual Ed25519 challenge that binds a declared identity to a key, and the G0→G3 attention ladder keyed on the counterparty rather than the request.
* **Task inbox and state machine** — `agent_id/inbox/state.py`: intake gate, review gate, rate limits, stale expiry, hash-chained audit.
* **Shield T0–T5** — `agent_id/inbox/{shield,intel,classifier,plandiff,corpus}.py`: deterministic layers, URL/domain/hash intelligence, the T4 ensemble, plan diffing, and the corpus that publishes error rates.
* **Settlement policy** — `agent_id/inbox/payments.py`: owner policy, signed quotes and receipts behind HTTP 402.
* **Governance** — `agent_id/inbox/governance.py`: appeals, pardons, advisory reputation federation.
* **Canonical Matrix Core**: High-density 256-Byte vector topological clustering powering 140k natural human personality profiles and industrial tolerance matching.

The 2026-09-05 sync also adds the **AI-era hardening** (mandatory T5, identity-cost tier caps, provenance-gated memory, rotation demotes, paid ≠ authorized). See `CHANGELOG.md`.

---

## 4. Package Distribution & Integration Model

### Why Not File Copying?
Copying code (`vendoring`) causes **protocol drift** where Agent ID and Human ID implementations diverge within weeks, breaking cross-network signature validation.

### Why Not Pure HTTP Microservices?
Cryptographic signatures (ECDSA/Ed25519) and 256-bit vector operations execute in under 0.2 milliseconds locally. Routing them through remote HTTP hops adds unnecessary latency and exposes private signing keys to network attack vectors.

### The Standard Solution: Semantic Package Dependencies
Twin3 SDK follows standard modern packaging conventions (`pyproject.toml` / `npm`). Production consumers must use immutable registry artifacts and exact version pins; local links are development-only.

#### 1. Development Mode (Local Symlink / Editable Install)
During local development, both `agent-id` and `XHuman_ID` link directly to the local SDK workspace:
```bash
# In agent-id or XHuman_ID virtual environment:
pip install -e /path/to/twin3-sdk
```
**Benefits**:
* Zero code duplication.
* Any protocol or algorithm improvement in `twin3-sdk` is reflected in both applications in **0 milliseconds**.

#### 2. Production Distribution
The next release candidate is `0.2.10-pre-alpha` for npm and `0.2.10a0` for Python. It is not a production dependency until the GitHub release workflows have built, attested, rehearsed, and published the exact tagged artifacts. Consumers must then pin the exact released version and lock its registry integrity; never use a mutable range for a cryptographic protocol dependency. This candidate stays pre-alpha. Marketplace or sales copy may offer it for evaluation; it is not a stable release, and the npm dist-tag is `next`, not `latest`.

`package.json` `engines` sets Node.js to `>=18` and does not set an npm engine. Any npm that can install a tarball can consume the package. Packing this repository was checked with npm 10 or newer; the stricter npm version in the release runbook applies only to Trusted Publishing.

After the release workflow has published that exact version, install the pin. These commands are not evidence that the registry already serves the package:

```bash
npm install twin3-sdk@0.2.10-pre-alpha
pip install twin3-sdk==0.2.10a0
```

Until publication, evaluate the packed npm tarball only. Do not install from a git URL or a version range:

```bash
npm pack --ignore-scripts
npm install ./twin3-sdk-0.2.10-pre-alpha.tgz
```

---

## 5. Dual-Application Projections

### 🏢 Agent ID (Enterprise Commerce Projection)
Agent ID consumes Twin3 SDK to execute the **5-Stage A2A Autonomous Commercial Loop**:
1. **Discovery**: Queries `twin3.discovery` for available suppliers and verified agent cards.
2. **Understand**: Uses `twin3.matrix` to compute tolerance matching against industrial RFQs.
3. **Negotiate**: Uses `twin3.comm` and `twin3.shield` to exchange signed quotes without prompt-tampering risks.
4. **Settle**: Uses the Twin3 signed-receipt adapter at an HTTP 402 gate. Acceptance additionally requires a trusted signer key, a chain-specific finality verifier, and a shared replay store.
5. **Dispute**: Invokes `twin3.governance` to resolve contractual non-performance.

### 👤 Human ID (Personal Sovereignty Projection)
Human ID consumes Twin3 SDK to empower natural individuals:
1. **140,000 Real Personality Assets**: Computes high-density personality matching via `twin3.matrix` without risking underlying database schemas.
2. **Passkey WebAuthn Login**: Binds biometric secure enclaves to decentralized keys via `twin3.trust`.
3. **Paid Inbox**: Protects individual inboxes against spam using `twin3.comm` and the signed-receipt adapter ($5 paywall threshold); the application supplies chain verification and shared replay state.
4. **Sovereign Card**: Renders non-custodial credentials using `twin3.discovery`.

---

## 6. Directory Structure

```
twin3-sdk/
├── pyproject.toml               # Standard packaging definition (PEP 621)
├── README.md                    # Canonical English manual
├── LICENSE                      # Proprietary licence, all rights reserved
├── js/index.js                  # Node runtime; js/comm/counterparty.js = Inbox line, counterparty side
├── twin3/                       # Core SDK namespace
│   ├── __init__.py
│   ├── _compat.py               # One import surface mirroring agent_id.inbox
│   ├── discovery/               # L1: Cards, Endpoints, agents.json, public inbox declaration
│   ├── trust/                   # L2: KYA Handshake, did:web, Passkey Adapter
│   ├── comm/                    # L3: Envelope, Counterparty Table, TaskInbox, export, client (counterparty side)
│   ├── shield/                  # L4: T0–T3 defense, T1 intel, T4 classifier, T5 plan diff, corpus, memory gate
│   ├── matrix/                  # L5: 256-Byte Vector Topology Engine
│   ├── settlement/              # L6: HTTP 402 Micropayments, owner policy, quotes, receipts
│   └── governance/              # L7: Evidence Trail, Arbitration, appeals, federation
└── tests/                       # Hermetic standalone Python and Node test suites
    ├── test_{discovery,trust,comm,shield,matrix,settlement,governance}.py
    ├── test_{envelope,counterparty,kya_gate,inbox_gate,plan_diff_gate}.py   # ported contracts
    ├── test_{classifier,intel,corpus_eval,settlement_policy,governance_gate,declaration,export}.py
    └── test_ai_era_hardening.py                                              # the five hardening rules
```

---

## 7. License

**Proprietary. All rights reserved.** Twin3 SDK is not open-source software. See [`LICENSE`](LICENSE) for the exact terms.

Distribution artifacts are published to public package registries so that anyone can install and evaluate the SDK and build against it — **open access is not open source**. Public availability grants no right to copy, modify, redistribute, fork, or create derivative works, and no patent or trademark licence. For commercial licensing or redistribution rights, contact core@twin3.ai.
