aionis-sdk 0.2.21

Python SDK for Aionis Memory Graph API

aionis-sdk

Python SDK for Aionis Memory Graph API.

Install

pip install aionis-sdk==0.2.21

Local Lite Runtime

The Python SDK is a client package.

For local development, use the official Aionis CLI from the TypeScript package to start Lite:

npx @aionis/sdk@0.2.21 dev

Then point the Python client at the local base URL:

from aionis_sdk import AionisClient

client = AionisClient(base_url="http://127.0.0.1:3321")

This is the recommended path for:

1. Python SDK evaluation
2. local write/recall/handoff/replay testing
3. single-machine developer setup without a separate local Aionis repo

Usage

import os
from aionis_sdk import AionisClient

client = AionisClient(
    base_url="http://127.0.0.1:3321",
    timeout_s=10.0,
    api_key=os.getenv("API_KEY"),           # optional: X-Api-Key
    auth_bearer=os.getenv("AUTH_BEARER"),   # optional: Authorization: Bearer <token>
    admin_token=os.getenv("ADMIN_TOKEN"),   # optional: X-Admin-Token
)

out = client.write(
    {
        "scope": "default",
        "input_text": "python sdk write",
        "auto_embed": False,
        "nodes": [{"client_id": "py_evt_1", "type": "event", "text_summary": "hello python sdk"}],
        "edges": [],
    }
)

print(out["status"], out["request_id"], out["data"]["commit_id"])

For Aionis Doc continuity flows, the Python client now also exposes high-level helpers:

resumed = client.doc_recover_and_resume(
    {
        "recover_request": {"anchor": "aionis-doc:workflow-001", "scope": "default"},
        "input_kind": "handoff-store-request",
        "candidates": ["resume_patch", "request_review"],
        "feedback_outcome": "positive",
    }
)

print(resumed["resume_summary"]["resume_state"])
print(resumed["resume_summary"]["lifecycle_transition"])

For a complete Python + CLI first-run flow, see:

1. Python SDK + Aionis CLI

Typed payloads

0.2.0+ exports TypedDict API payloads from aionis_sdk.types:

from aionis_sdk import AionisClient
from aionis_sdk.types import ToolsFeedbackInput, ToolsSelectInput

client = AionisClient(base_url="http://localhost:3001")

select_payload: ToolsSelectInput = {
    "scope": "default",
    "run_id": "run_001",
    "context": {"intent": "json", "provider": "minimax", "tool": {"name": "curl"}},
    "candidates": ["curl", "bash"],
    "strict": True,
}
select_out = client.tools_select(select_payload)
decision_id = (select_out.get("data") or {}).get("decision", {}).get("decision_id")

feedback_payload: ToolsFeedbackInput = {
    "scope": "default",
    "run_id": "run_001",
    "decision_id": decision_id,
    "outcome": "positive",
    "context": {"intent": "json", "provider": "minimax", "tool": {"name": "curl"}},
    "candidates": ["curl", "bash"],
    "selected_tool": "curl",
}
client.tools_feedback(feedback_payload)
client.tools_run({"scope": "default", "run_id": "run_001"})

Auth Options

1. api_key: sends X-Api-Key.
2. auth_bearer: sends Authorization: Bearer <token>.
3. admin_token: sends X-Admin-Token (debug/admin flows).

Covered methods

1. write
2. recall
3. recall_text
4. context_assemble
5. planning_context
6. find
7. list_sessions
8. create_session
9. write_event
10. list_session_events
11. pack_export
12. pack_import
13. archive_rehydrate
14. nodes_activate
15. handoff_store
16. handoff_recover
17. sandbox_create_session
18. sandbox_execute
19. sandbox_run_get
20. sandbox_run_logs
21. sandbox_run_artifact
22. sandbox_run_cancel
23. rules_evaluate
24. rules_state
25. tools_select
26. tools_decision
27. tools_run
28. tools_feedback
29. feedback
30. replay_run_start
31. replay_step_before
32. replay_step_after
33. replay_run_end
34. replay_run_get
35. replay_playbook_compile_from_run
36. replay_playbook_get
37. replay_playbook_candidate
38. replay_playbook_promote
39. replay_playbook_repair
40. replay_playbook_repair_review
41. replay_playbook_run
42. replay_playbook_dispatch
43. automation_create
44. automation_get
45. automation_list
46. automation_telemetry
47. automation_assign_reviewer
48. automation_promote
49. automation_validate
50. automation_graph_validate
51. automation_shadow_report
52. automation_shadow_review
53. automation_shadow_validate
54. automation_shadow_validate_dispatch
55. automation_compensation_policy_matrix
56. automation_run
57. automation_run_get
58. automation_run_list
59. automation_run_assign_reviewer
60. automation_run_cancel
61. automation_run_approve_repair
62. automation_run_compensation_retry
63. automation_run_compensation_assign
64. automation_run_compensation_record_action
65. automation_run_resume
66. automation_run_reject_repair
67. doc_recover
68. doc_resume
69. doc_recover_and_resume
70. health
71. get_capability_contract

Admin/control methods (require admin_token):

1. control_upsert_tenant, control_list_tenants, control_upsert_project
2. control_create_api_key, control_list_api_keys, control_list_stale_api_keys, control_revoke_api_key, control_rotate_api_key
3. control_create_alert_route, control_list_alert_routes, control_update_alert_route_status, control_list_alert_deliveries
4. control_enqueue_incident_publish_job, control_list_incident_publish_jobs, control_replay_incident_publish_jobs
5. control_upsert_tenant_quota, control_get_tenant_quota, control_delete_tenant_quota
6. control_upsert_sandbox_budget, control_get_sandbox_budget, control_delete_sandbox_budget, control_list_sandbox_budgets
7. control_list_audit_events, control_get_tenant_dashboard, control_get_tenant_diagnostics
8. control_get_tenant_incident_publish_rollup, control_get_tenant_incident_publish_slo, control_get_tenant_timeseries, control_get_tenant_key_usage

Error model

1. AionisApiError: API returned non-2xx response.
2. AionisNetworkError: request timeout/network failure.

Capability-aware helpers:

1. is_backend_capability_unsupported_error(err)
2. parse_backend_capability_error_details(err.details)
3. is_shadow_dual_write_strict_failure_error(err)
4. parse_shadow_dual_write_strict_failure_details(err.details)

from aionis_sdk import AionisApiError, is_backend_capability_unsupported_error

try:
    client.pack_export({"scope": "default"})
except Exception as err:
    if is_backend_capability_unsupported_error(err):
        print(err.details.get("capability"), err.details.get("failure_mode"))
    elif isinstance(err, AionisApiError):
        print(err.code, str(err))

Smoke

set -a; source .env; set +a
npm run sdk:py:smoke

Build check (repo local)

npm run sdk:py:compile
npm run sdk:py:release-check