diff --git a/README.md b/README.md index dbb1d23..cc5330e 100644 --- a/README.md +++ b/README.md @@ -131,7 +131,7 @@ Full runnable scenario set lives in: The SDK covers the full public API surface organized into families. The map below shows all method groups and how they relate to the platform's intent lifecycle. -![API Method Family Map](docs/diagrams/01-api-method-family-map.svg) +![API Method Family Map](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/api/01-api-method-family-map.svg) *Each family corresponds to a segment of the lifecycle or an operational domain. Intents and inbox are D1 (core). Approvals, schemas, and media are D2. Enterprise admin and service accounts are D3.* @@ -141,7 +141,7 @@ The SDK covers the full public API surface organized into families. The map belo From calling `create_intent()` to receiving a delivery confirmation — the full interaction sequence with the platform: -![Create and Control Sequence](docs/diagrams/02-create-and-control-sequence.svg) +![Create and Control Sequence](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/intents/02-create-and-control-sequence.svg) *The SDK sets the `Idempotency-Key` and `X-Correlation-Id` headers automatically. The gateway validates, persists, and returns the intent in `PENDING` state. The scheduler picks it up and drives delivery.* @@ -151,7 +151,7 @@ From calling `create_intent()` to receiving a delivery confirmation — the full Every mutating call in the SDK accepts an optional `idempotency_key`. Use it for all operations you might retry. -![Idempotency and Replay Protection](docs/diagrams/03-idempotency-and-replay-protection.svg) +![Idempotency and Replay Protection](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/protocol/03-idempotency-and-replay-protection.svg) *Duplicate requests with the same key return the original response without re-executing. Keys expire after 24 hours. The SDK will warn if you reuse a key with different parameters.* @@ -221,9 +221,9 @@ The SDK docs folder contains diagrams for the API patterns used by this client: | Diagram | Description | |---|---| -| [`01-api-method-family-map`](docs/diagrams/01-api-method-family-map.svg) | Full API family overview | -| [`02-create-and-control-sequence`](docs/diagrams/02-create-and-control-sequence.svg) | Intent creation and control flow | -| [`03-idempotency-and-replay-protection`](docs/diagrams/03-idempotency-and-replay-protection.svg) | Idempotency protocol | +| [`01-api-method-family-map`](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/api/01-api-method-family-map.svg) | Full API family overview | +| [`02-create-and-control-sequence`](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/intents/02-create-and-control-sequence.svg) | Intent creation and control flow | +| [`03-idempotency-and-replay-protection`](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/protocol/03-idempotency-and-replay-protection.svg) | Idempotency protocol | --- @@ -277,7 +277,6 @@ axme-sdk-python/ ├── examples/ │ └── basic_submit.py # Minimal language-native quickstart └── docs/ - └── diagrams/ # Diagram copies for README embedding ``` --- diff --git a/docs/diagrams/01-api-method-family-map.svg b/docs/diagrams/01-api-method-family-map.svg deleted file mode 100644 index a450cbe..0000000 --- a/docs/diagrams/01-api-method-family-map.svg +++ /dev/null @@ -1,276 +0,0 @@ - - - - - - -api_method_map - - -cluster_intents - -Intents Family - - -cluster_inbox - -Inbox + Approvals - - -cluster_platform - -Platform Helpers - - - -API - - -Public API Surface - - - -I1 - -POST /v1/intents - - - -API->I1 - - - - - -I2 - -GET /v1/intents/{id} - - - -API->I2 - - - - - -I3 - -GET /v1/intents/{id}/events - - - -API->I3 - - - - - -I4 - -GET /v1/intents/{id}/events/stream - - - -API->I4 - - - - - -I5 - -POST /v1/intents/{id}/resume - - - -API->I5 - - - - - -I6 - -POST /v1/intents/{id}/controls - - - -API->I6 - - - - - -I7 - -POST /v1/intents/{id}/policy - - - -API->I7 - - - - - -I8 - -POST /v1/intents/{id}/resolve - - - -API->I8 - - - - - -B1 - -GET /v1/inbox - - - -API->B1 - - - - - -B2 - -GET /v1/inbox/{thread_id} - - - -API->B2 - - - - - -B3 - -POST /v1/inbox/{id}/reply - - - -API->B3 - - - - - -B4 - -POST /v1/inbox/{id}/delegate - - - -API->B4 - - - - - -B5 - -POST /v1/inbox/{id}/approve - - - -API->B5 - - - - - -B6 - -POST /v1/inbox/{id}/reject - - - -API->B6 - - - - - -B7 - -POST /v1/approvals/{id}/decision - - - -API->B7 - - - - - -P1 - -Schemas API - - - -API->P1 - - - - - -P2 - -Webhooks API - - - -API->P2 - - - - - -P3 - -Users + Auth API - - - -API->P3 - - - - - -P4 - -Media API - - - -API->P4 - - - - - -CLI - -Client / SDK -HTTPS methods - - - -CLI->API - - - - - diff --git a/docs/diagrams/02-create-and-control-sequence.svg b/docs/diagrams/02-create-and-control-sequence.svg deleted file mode 100644 index 523f8a2..0000000 --- a/docs/diagrams/02-create-and-control-sequence.svg +++ /dev/null @@ -1,285 +0,0 @@ - - - - - - -create_and_control - - -cluster_client - -Client/SDK - - -cluster_axme - -AXME Cloud - - -cluster_recipient - -Recipient Agent - - - -C1 - -Client/SDK -POST /v1/intents - - - -G1 - -Gateway -validate auth+schema+idempotency - - - -C1->G1 - - - - - -R1 - -Runtime+Store -persist intent -policy_generation=0 - - - -G1->R1 - - - - - -B1 - -Recipient Agent -routed via registry - - - -G1->B1 - - - - - -G2 - -Gateway -201 accepted + intent_id - - - -G1->G2 - - -return - - - -G2->C1 - - -return - - - -C2 - -Client/SDK -POST /intents/{id}/controls or /policy -(expected_policy_generation=n) - - - -G3 - -Gateway -compare generation - - - -C2->G3 - - - - - -R2 - -Store -atomic update -generation=n+1 - - - -G3->R2 - - -generation matches - - - -G5 - -Gateway -409 conflict - - - -G3->G5 - - -generation mismatch - - - -G4 - -Gateway -200 updated generation - - - -R2->G4 - - -return - - - -G4->C2 - - -return - - - -C3 - -Client/SDK -GET /intents/{id} -fetch latest generation - - - -G5->C3 - - -return - - - -C3->G3 - - -retry with new generation - - - -B2 - -Recipient Agent -progress/waiting/completion - - - -G6 - -Gateway -status update - - - -B2->G6 - - -update state - - - -G6->R1 - - -update state - - - -C4 - -Client/SDK -POST /intents/{id}/resume - - - -R3 - -Runtime -continue waiting run - - - -C4->R3 - - -return - - - -G7 - -Gateway -state advanced - - - -R3->G7 - - -return - - - -G7->C4 - - -return - - - -S1 - -Internal Scheduler -wakeup tick - - - -R4 - -Runtime -advance via scheduler - - - -S1->R4 - - - - - -R4->G6 - - - - - diff --git a/docs/diagrams/03-idempotency-and-replay-protection.svg b/docs/diagrams/03-idempotency-and-replay-protection.svg deleted file mode 100644 index ea8bab3..0000000 --- a/docs/diagrams/03-idempotency-and-replay-protection.svg +++ /dev/null @@ -1,131 +0,0 @@ - - - - - - -idempotency - - - -REQ - -Incoming Request - - - -IDK - -extract idempotency_key - - - -REQ->IDK - - - - - -LOOK - -key in store? - - - -IDK->LOOK - - - - - -DUP - -same payload? - - - -LOOK->DUP - - -yes - - - -EXEC - -execute operation - - - -LOOK->EXEC - - -no - - - -CACHE - -return cached 200 - - - -DUP->CACHE - - -yes - - - -CONF - -409 Conflict - - - -DUP->CONF - - -no - - - -STORE - -persist result + key - - - -EXEC->STORE - - - - - -RESP - -return response - - - -STORE->RESP - - - - - -TTL - -expire key after TTL - - - -STORE->TTL - - - - -