axon-protocol 0.1.0__tar.gz

axon_protocol-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sarthak Dhatrak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

axon_protocol-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: axon-protocol
+Version: 0.1.0
+Summary: Python SDK for Axon Protocol — persistent memory, coordination, and reasoning receipts for AI agents
+Author-email: Sarthak Dhatrak <sarthakmdhtr@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/axon-protocol/axon-sdk-python
+Project-URL: Documentation, https://docs.axon.so
+Project-URL: Repository, https://github.com/axon-protocol/axon-sdk-python
+Project-URL: Issues, https://github.com/axon-protocol/axon-sdk-python/issues
+Keywords: ai,agents,memory,coordination,llm,multiagent,axon
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: respx>=0.21.0; extra == "dev"
+Dynamic: license-file
+
+# Axon Protocol — Python SDK (`axon-protocol`)
+
+Official Python client library for integration with the Axon core server. Handles semantic memory, coordination locks, and tamper-proof reasoning receipts for multi-agent AI environments.
+
+---
+
+## Installation
+
+Install the library locally:
+```bash
+pip install axon-protocol
+```
+
+---
+
+## Quickstart
+
+### Async Usage
+
+```python
+import asyncio
+from axon import AxonClient
+
+async def main():
+    async with AxonClient(api_key="axon-...", project_id="my-project") as axon:
+        # Store memory
+        await axon.memory.store("User prefers dark mode")
+        
+        # Search memory
+        results = await axon.memory.search("ui preferences")
+        print(results.results[0].content)
+
+        # Acquire lock
+        async with axon.lock("resource_1"):
+            print("Lock held!")
+
+asyncio.run(main())
+```
+
+### Sync Usage
+
+```python
+from axon import AxonSyncClient
+
+with AxonSyncClient(api_key="axon-...", project_id="my-project") as axon:
+    # Store memory
+    axon.memory.store("User prefers dark mode")
+    
+    # Search memory
+    results = axon.memory.search("ui preferences")
+    print(results.results[0].content)
+
+    # Acquire lock
+    with axon.lock("resource_1"):
+        print("Lock held!")
+```
+
+---
+
+## Features
+
+### A. Persistent Memory (Semantic Vector Search)
+
+Store memories and query them with semantic similarity matching:
+
+```python
+# Async
+memory_id = await axon.memory.store(
+    content="The API service key is stored in the vault.",
+    tags={"category": "vault"},
+    scope="project",
+    ttl=3600  # auto-expire in 1 hour
+)
+
+results = await axon.memory.search(
+    query="Where is the API key?",
+    limit=5,
+    min_similarity=0.6
+)
+```
+
+### B. Resource Locking (Mutex)
+
+Prevent race conditions in multi-agent environments. Use the lock context manager to automatically release locks:
+
+```python
+# Sync Lock Context Manager
+with axon.lock("resource_lock", timeout=60) as lock:
+    # Exclusive access section
+    print(f"Lock acquired, expires at: {lock.expires_at}")
+```
+
+### C. Reasoning Steps Recording
+
+Generate cryptographically chained, signed receipts validating agent reasoning processes:
+
+```python
+# Async receipt creation
+receipt = await axon.receipts.create(
+    input="Fix the login bug in auth.py",
+    steps=[
+        ReasoningStep(thought="Read the login function"),
+        ReasoningStep(
+            thought="Found missing token validation",
+            tool_called="read_file",
+            result="Null check missing at line 47"
+        )
+    ],
+    output="Bug fixed"
+)
+
+# Automated decoration
+@axon.receipts.track(input_param="task")
+async def agent_function(task: str, steps_logger=None) -> str:
+    steps_logger.add(thought="Analyzing the task")
+    return "Done"
+```
+
+### D. Real-Time Events Stream
+
+Listen to event streams (like memory additions or lock releases) happening across your project:
+
+```python
+# Async stream
+async for event in axon.events.listen():
+    print(f"Event Captured: {event['event_type']}")
+```

axon_protocol-0.1.0/README.md

@@ -0,0 +1,127 @@
+# Axon Protocol — Python SDK (`axon-protocol`)
+
+Official Python client library for integration with the Axon core server. Handles semantic memory, coordination locks, and tamper-proof reasoning receipts for multi-agent AI environments.
+
+---
+
+## Installation
+
+Install the library locally:
+```bash
+pip install axon-protocol
+```
+
+---
+
+## Quickstart
+
+### Async Usage
+
+```python
+import asyncio
+from axon import AxonClient
+
+async def main():
+    async with AxonClient(api_key="axon-...", project_id="my-project") as axon:
+        # Store memory
+        await axon.memory.store("User prefers dark mode")
+        
+        # Search memory
+        results = await axon.memory.search("ui preferences")
+        print(results.results[0].content)
+
+        # Acquire lock
+        async with axon.lock("resource_1"):
+            print("Lock held!")
+
+asyncio.run(main())
+```
+
+### Sync Usage
+
+```python
+from axon import AxonSyncClient
+
+with AxonSyncClient(api_key="axon-...", project_id="my-project") as axon:
+    # Store memory
+    axon.memory.store("User prefers dark mode")
+    
+    # Search memory
+    results = axon.memory.search("ui preferences")
+    print(results.results[0].content)
+
+    # Acquire lock
+    with axon.lock("resource_1"):
+        print("Lock held!")
+```
+
+---
+
+## Features
+
+### A. Persistent Memory (Semantic Vector Search)
+
+Store memories and query them with semantic similarity matching:
+
+```python
+# Async
+memory_id = await axon.memory.store(
+    content="The API service key is stored in the vault.",
+    tags={"category": "vault"},
+    scope="project",
+    ttl=3600  # auto-expire in 1 hour
+)
+
+results = await axon.memory.search(
+    query="Where is the API key?",
+    limit=5,
+    min_similarity=0.6
+)
+```
+
+### B. Resource Locking (Mutex)
+
+Prevent race conditions in multi-agent environments. Use the lock context manager to automatically release locks:
+
+```python
+# Sync Lock Context Manager
+with axon.lock("resource_lock", timeout=60) as lock:
+    # Exclusive access section
+    print(f"Lock acquired, expires at: {lock.expires_at}")
+```
+
+### C. Reasoning Steps Recording
+
+Generate cryptographically chained, signed receipts validating agent reasoning processes:
+
+```python
+# Async receipt creation
+receipt = await axon.receipts.create(
+    input="Fix the login bug in auth.py",
+    steps=[
+        ReasoningStep(thought="Read the login function"),
+        ReasoningStep(
+            thought="Found missing token validation",
+            tool_called="read_file",
+            result="Null check missing at line 47"
+        )
+    ],
+    output="Bug fixed"
+)
+
+# Automated decoration
+@axon.receipts.track(input_param="task")
+async def agent_function(task: str, steps_logger=None) -> str:
+    steps_logger.add(thought="Analyzing the task")
+    return "Done"
+```
+
+### D. Real-Time Events Stream
+
+Listen to event streams (like memory additions or lock releases) happening across your project:
+
+```python
+# Async stream
+async for event in axon.events.listen():
+    print(f"Event Captured: {event['event_type']}")
+```

axon_protocol-0.1.0/axon/__init__.py

@@ -0,0 +1,51 @@
+from axon.client import AxonClient, AxonSyncClient
+from axon.messages import MessagesClient, SyncMessagesClient
+from axon.types import (
+    MemoryResult,
+    MemorySearchResponse,
+    StoredMemory,
+    LockInfo,
+    LockStatus,
+    ReasoningStep,
+    StepsLogger,
+    ReceiptInfo,
+    ReceiptVerifyResult,
+)
+from axon.exceptions import (
+    AxonError,
+    AuthError,
+    LockConflictError,
+    NotFoundError,
+    AxonPermissionError,
+    RateLimitError,
+    ServerError,
+    AxonConnectionError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AxonClient",
+    "AxonSyncClient",
+    "MessagesClient",
+    "SyncMessagesClient",
+    # Types
+    "MemoryResult",
+    "MemorySearchResponse",
+    "StoredMemory",
+    "LockInfo",
+    "LockStatus",
+    "ReasoningStep",
+    "StepsLogger",
+    "ReceiptInfo",
+    "ReceiptVerifyResult",
+    # Exceptions
+    "AxonError",
+    "AuthError",
+    "LockConflictError",
+    "NotFoundError",
+    "AxonPermissionError",
+    "RateLimitError",
+    "ServerError",
+    "AxonConnectionError",
+]

axon_protocol-0.1.0/axon/_base.py

@@ -0,0 +1,142 @@
+import httpx
+import time
+import asyncio
+from axon.exceptions import (
+    AuthError,
+    NotFoundError,
+    AxonPermissionError,
+    LockConflictError,
+    RateLimitError,
+    ServerError,
+    AxonConnectionError,
+)
+
+
+class _BaseClient:
+    def __init__(self, http: httpx.AsyncClient, base_url: str):
+        self._http = http
+        self._base_url = base_url.rstrip("/")
+
+    async def _request(self, method: str, path: str, **kwargs) -> dict:
+        url = f"{self._base_url}{path}"
+        retries = 3
+        backoff = 0.5
+
+        for attempt in range(retries):
+            try:
+                response = await self._http.request(method, url, **kwargs)
+                if response.status_code >= 500 and attempt < retries - 1:
+                    await asyncio.sleep(backoff * (2 ** attempt))
+                    continue
+                break
+            except httpx.ConnectError:
+                if attempt == retries - 1:
+                    raise AxonConnectionError(
+                        f"Cannot connect to Axon server at {self._base_url}. "
+                        f"Make sure the server is running."
+                    )
+                await asyncio.sleep(backoff * (2 ** attempt))
+            except httpx.TimeoutException:
+                if attempt == retries - 1:
+                    raise AxonConnectionError(
+                        f"Request to {url} timed out. Server may be overloaded."
+                    )
+                await asyncio.sleep(backoff * (2 ** attempt))
+
+        # Success
+        if response.status_code == 200:
+            return response.json()
+
+        # Parse error detail from response body
+        try:
+            detail = response.json().get("detail", response.text)
+        except Exception:
+            detail = response.text
+
+        # Map status codes to specific exceptions
+        if response.status_code == 401:
+            raise AuthError(f"Authentication failed: {detail}", 401)
+        elif response.status_code == 403:
+            raise AxonPermissionError(f"Permission denied: {detail}", 403)
+        elif response.status_code == 404:
+            raise NotFoundError(f"Not found: {detail}", 404)
+        elif response.status_code == 409:
+            raise LockConflictError("", detail=detail)
+        elif response.status_code == 429:
+            retry_after = int(response.headers.get("Retry-After", 60))
+            raise RateLimitError(retry_after)
+        elif response.status_code >= 500:
+            raise ServerError(
+                f"Server error ({response.status_code}): {detail}",
+                response.status_code,
+            )
+        else:
+            raise ServerError(
+                f"Unexpected status {response.status_code}: {detail}",
+                response.status_code,
+            )
+
+
+class _BaseSyncClient:
+    def __init__(self, http: httpx.Client, base_url: str):
+        self._http = http
+        self._base_url = base_url.rstrip("/")
+
+    def _request(self, method: str, path: str, **kwargs) -> dict:
+        url = f"{self._base_url}{path}"
+        retries = 3
+        backoff = 0.5
+
+        for attempt in range(retries):
+            try:
+                response = self._http.request(method, url, **kwargs)
+                if response.status_code >= 500 and attempt < retries - 1:
+                    time.sleep(backoff * (2 ** attempt))
+                    continue
+                break
+            except httpx.ConnectError:
+                if attempt == retries - 1:
+                    raise AxonConnectionError(
+                        f"Cannot connect to Axon server at {self._base_url}. "
+                        f"Make sure the server is running."
+                    )
+                time.sleep(backoff * (2 ** attempt))
+            except httpx.TimeoutException:
+                if attempt == retries - 1:
+                    raise AxonConnectionError(
+                        f"Request to {url} timed out. Server may be overloaded."
+                    )
+                time.sleep(backoff * (2 ** attempt))
+
+        # Success
+        if response.status_code == 200:
+            return response.json()
+
+        # Parse error detail from response body
+        try:
+            detail = response.json().get("detail", response.text)
+        except Exception:
+            detail = response.text
+
+        # Map status codes to specific exceptions
+        if response.status_code == 401:
+            raise AuthError(f"Authentication failed: {detail}", 401)
+        elif response.status_code == 403:
+            raise AxonPermissionError(f"Permission denied: {detail}", 403)
+        elif response.status_code == 404:
+            raise NotFoundError(f"Not found: {detail}", 404)
+        elif response.status_code == 409:
+            raise LockConflictError("", detail=detail)
+        elif response.status_code == 429:
+            retry_after = int(response.headers.get("Retry-After", 60))
+            raise RateLimitError(retry_after)
+        elif response.status_code >= 500:
+            raise ServerError(
+                f"Server error ({response.status_code}): {detail}",
+                response.status_code,
+            )
+        else:
+            raise ServerError(
+                f"Unexpected status {response.status_code}: {detail}",
+                response.status_code,
+            )

axon_protocol-0.1.0/axon/client.py

@@ -0,0 +1,132 @@
+import httpx
+from axon.memory import MemoryClient, SyncMemoryClient
+from axon.coordination import CoordinationClient, SyncCoordinationClient
+from axon.receipts import ReceiptsClient, SyncReceiptsClient
+from axon.events import EventsClient, SyncEventsClient
+from axon.messages import MessagesClient, SyncMessagesClient
+
+
+class AxonClient:
+    """
+    Async entry point for the Axon Protocol Python SDK.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        project_id: str,
+        agent_token: str = None,
+        agent_id: str = None,
+        base_url: str = "http://localhost:8000",
+        timeout: float = 30.0,
+    ):
+        self.api_key = api_key
+        self.project_id = project_id
+        self.agent_token = agent_token
+        self.agent_id = agent_id
+        self.base_url = base_url.rstrip("/")
+
+        headers = {}
+        if api_key:
+            headers["X-API-Key"] = api_key
+        if agent_token:
+            headers["Authorization"] = f"Bearer {agent_token}"
+
+        self._http = httpx.AsyncClient(
+            headers=headers,
+            timeout=httpx.Timeout(timeout),
+            limits=httpx.Limits(
+                max_connections=20,
+                max_keepalive_connections=10,
+                keepalive_expiry=30,
+            ),
+        )
+
+        self.memory = MemoryClient(self._http, self.base_url)
+        self.lock = CoordinationClient(self._http, self.base_url)
+        self.receipts = ReceiptsClient(self._http, self.base_url)
+        self.events = EventsClient(self.base_url, api_key, project_id)
+        self.messages = MessagesClient(self._http, self.base_url)
+
+    async def ping(self) -> bool:
+        """
+        Check if the Axon server is reachable (async).
+        """
+        try:
+            response = await self._http.get(f"{self.base_url}/v1/health")
+            return response.status_code == 200
+        except Exception:
+            return False
+
+    async def close(self):
+        """Close the underlying HTTP connection pool."""
+        await self._http.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+
+
+class AxonSyncClient:
+    """
+    Sync entry point for the Axon Protocol Python SDK.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        project_id: str,
+        agent_token: str = None,
+        agent_id: str = None,
+        base_url: str = "http://localhost:8000",
+        timeout: float = 30.0,
+    ):
+        self.api_key = api_key
+        self.project_id = project_id
+        self.agent_token = agent_token
+        self.agent_id = agent_id
+        self.base_url = base_url.rstrip("/")
+
+        headers = {}
+        if api_key:
+            headers["X-API-Key"] = api_key
+        if agent_token:
+            headers["Authorization"] = f"Bearer {agent_token}"
+
+        self._http = httpx.Client(
+            headers=headers,
+            timeout=httpx.Timeout(timeout),
+            limits=httpx.Limits(
+                max_connections=20,
+                max_keepalive_connections=10,
+                keepalive_expiry=30,
+            ),
+        )
+
+        self.memory = SyncMemoryClient(self._http, self.base_url)
+        self.lock = SyncCoordinationClient(self._http, self.base_url)
+        self.receipts = SyncReceiptsClient(self._http, self.base_url)
+        self.events = SyncEventsClient(self.base_url, api_key, project_id)
+        self.messages = SyncMessagesClient(self._http, self.base_url)
+
+    def ping(self) -> bool:
+        """
+        Check if the Axon server is reachable (sync).
+        """
+        try:
+            response = self._http.get(f"{self.base_url}/v1/health")
+            return response.status_code == 200
+        except Exception:
+            return False
+
+    def close(self):
+        """Close the underlying HTTP connection pool."""
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()