Metadata-Version: 2.4
Name: twin3-sdk
Version: 0.2.12a0
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: local-memory
Requires-Dist: pypdf==6.19.0; extra == "local-memory"
Provides-Extra: dev
Requires-Dist: pypdf==6.19.0; 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) | [Traditional Chinese](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
`v0.2.12-pre-alpha` is the current release candidate: `0.2.12-pre-alpha` for npm and `0.2.12a0` for PyPI. Publication is pending. Consumers must pin the exact released version and lock its registry integrity; never use a mutable range for a cryptographic protocol dependency. This release 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 publication, install the exact released version from the registry:

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

For local evaluation, you can also use the packed npm tarball. Do not install from a git URL or a version range:

```bash
npm pack --ignore-scripts
npm install ./twin3-sdk-0.2.12-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.
