axon-protocol-cli 0.1.0__tar.gz

axon_protocol_cli-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: axon-protocol-cli
+Version: 0.1.0
+Summary: CLI tool for Axon Protocol — interact with your Axon server from the terminal
+Author-email: Sarthak Dhatrak <sarthakmdhtr@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/axon-protocol/axon-cli
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: httpx>=0.27.0
+
+# Axon Protocol CLI (`axon-cli`)
+
+The official command-line interface for the **Axon Protocol** ecosystem. Monitor and manage agents, memory, locks, and receipts directly from your terminal.
+
+---
+
+## Installation
+
+Install `axon-cli` locally in editable mode:
+
+```bash
+cd e:\Axon\axon-cli
+pip install -e .
+```
+
+To install from production (once published):
+
+```bash
+pip install axon-cli
+```
+
+---
+
+## Command Reference
+
+### System Initialization & Health
+
+- **`axon init`**: Initialize or modify the `.axon` config file in the current directory.
+- **`axon doctor`**: Run quick readiness diagnostics on the database, Redis, and embedding model services.
+
+### Agent Management
+
+- **`axon agent register <name>`**: Register a new agent in a project. Automagically updates the local `.axon` config file with the newly generated API key.
+- **`axon agent me`**: Show current agent status, capabilities, and profile info.
+- **`axon agent list`**: List all agents registered in the active project.
+
+### Vector Memory
+
+- **`axon memory store "<content>"`**: Store a semantic memory.
+  - Option `-t, --tag key=value`: Attach custom metadata tags (can be passed multiple times).
+  - Option `-s, --scope <scope>`: Specify memory visibility scope (e.g. `agent` or `project`, defaults to `project`).
+  - Option `--ttl <seconds>`: Set time-to-live for the memory.
+- **`axon memory search "<query>"`**: Find semantically similar memories.
+  - Option `-l, --limit <n>`: Max results (default 10).
+  - Option `-m, --min-similarity <f>`: Similarity threshold (default 0.5).
+- **`axon memory list`**: List recent memories in the project.
+- **`axon memory delete <memory_id>`**: Delete a memory permanently.
+
+### Distributed Locking
+
+- **`axon lock list`**: List active locks in the project.
+- **`axon lock status <resource_id>`**: Get detailed status of a resource lock.
+- **`axon lock acquire <resource_id>`**: Acquire an exclusive lock on a resource.
+- **`axon lock release <resource_id>`**: Release a lock you hold.
+
+### Reasoning Receipts
+
+- **`axon receipt list`**: Browse recent receipts.
+- **`axon receipt show <receipt_id>`**: View complete details and reasoning chain for a receipt.
+- **`axon receipt verify <receipt_id>`**: Recompute and cryptographically verify a receipt's integrity.

axon_protocol_cli-0.1.0/README.md

@@ -0,0 +1,60 @@
+# Axon Protocol CLI (`axon-cli`)
+
+The official command-line interface for the **Axon Protocol** ecosystem. Monitor and manage agents, memory, locks, and receipts directly from your terminal.
+
+---
+
+## Installation
+
+Install `axon-cli` locally in editable mode:
+
+```bash
+cd e:\Axon\axon-cli
+pip install -e .
+```
+
+To install from production (once published):
+
+```bash
+pip install axon-cli
+```
+
+---
+
+## Command Reference
+
+### System Initialization & Health
+
+- **`axon init`**: Initialize or modify the `.axon` config file in the current directory.
+- **`axon doctor`**: Run quick readiness diagnostics on the database, Redis, and embedding model services.
+
+### Agent Management
+
+- **`axon agent register <name>`**: Register a new agent in a project. Automagically updates the local `.axon` config file with the newly generated API key.
+- **`axon agent me`**: Show current agent status, capabilities, and profile info.
+- **`axon agent list`**: List all agents registered in the active project.
+
+### Vector Memory
+
+- **`axon memory store "<content>"`**: Store a semantic memory.
+  - Option `-t, --tag key=value`: Attach custom metadata tags (can be passed multiple times).
+  - Option `-s, --scope <scope>`: Specify memory visibility scope (e.g. `agent` or `project`, defaults to `project`).
+  - Option `--ttl <seconds>`: Set time-to-live for the memory.
+- **`axon memory search "<query>"`**: Find semantically similar memories.
+  - Option `-l, --limit <n>`: Max results (default 10).
+  - Option `-m, --min-similarity <f>`: Similarity threshold (default 0.5).
+- **`axon memory list`**: List recent memories in the project.
+- **`axon memory delete <memory_id>`**: Delete a memory permanently.
+
+### Distributed Locking
+
+- **`axon lock list`**: List active locks in the project.
+- **`axon lock status <resource_id>`**: Get detailed status of a resource lock.
+- **`axon lock acquire <resource_id>`**: Acquire an exclusive lock on a resource.
+- **`axon lock release <resource_id>`**: Release a lock you hold.
+
+### Reasoning Receipts
+
+- **`axon receipt list`**: Browse recent receipts.
+- **`axon receipt show <receipt_id>`**: View complete details and reasoning chain for a receipt.
+- **`axon receipt verify <receipt_id>`**: Recompute and cryptographically verify a receipt's integrity.

axon_protocol_cli-0.1.0/axon_cli/__init__.py

@@ -0,0 +1 @@
+# axon_cli package

axon_protocol_cli-0.1.0/axon_cli/commands/__init__.py

@@ -0,0 +1 @@
+# axon_cli/commands package

axon_protocol_cli-0.1.0/axon_cli/commands/agent.py

@@ -0,0 +1,105 @@
+import click
+from axon_cli.http import AxonHttpClient
+from axon_cli.config import save_config, load_config
+from axon_cli.display import print_success, print_info, print_table, print_panel
+
+@click.group()
+def agent():
+    """Manage agents and agent registration."""
+    pass
+
+@agent.command("register")
+@click.argument("name")
+@click.option("--project-id", help="Project ID for the agent (defaults to config Project ID)")
+@click.option("--org-id", help="Organization ID (optional)")
+@click.option("-c", "--capability", multiple=True, help="Capabilities of the agent (e.g. -c memory -c planning)")
+def register(name, project_id, org_id, capability):
+    """Register a new agent with the Axon server."""
+    config = load_config()
+    target_project = project_id or config.get("project_id")
+    if not target_project:
+        target_project = click.prompt("Project ID")
+
+    # Connect to client
+    client = AxonHttpClient()
+    
+    payload = {
+        "name": name,
+        "project_id": target_project,
+        "org_id": org_id,
+        "capabilities": list(capability) if capability else []
+    }
+    
+    print_info(f"Registering agent '{name}' in project '{target_project}'...")
+    res = client.post("/v1/agents/register", json=payload)
+    
+    # Save Project key, project_id, and agent info to local config
+    api_key_to_save = res.get("api_key") or client.api_key or ""
+    save_config(
+        base_url=client.base_url,
+        api_key=api_key_to_save,
+        project_id=target_project,
+        agent_id=res["id"],
+        agent_token=res["token"]
+    )
+    
+    # Display registration result
+    content = (
+        f"[bold]Agent ID:[/bold] {res['id']}\n"
+        f"[bold]Name:[/bold] {res['name']}\n"
+        f"[bold]Project ID:[/bold] {res['project_id']}\n"
+        f"[bold]API Key:[/bold] [yellow]{api_key_to_save}[/yellow] *(Saved to .axon)*\n"
+        f"[bold]JWT Token:[/bold] {res['token'][:30]}...\n"
+        f"[bold]Created At:[/bold] {res['created_at']}"
+    )
+    print_panel("Agent Registered", content, subtitle="Configuration Auto-Updated")
+    print_success(f"Successfully registered and authenticated agent '{name}'!")
+
+@agent.command("me")
+def me():
+    """Get details of the currently authenticated agent."""
+    client = AxonHttpClient()
+    if not client.api_key:
+        raise click.ClickException("No API key configured. Run 'axon init' or 'axon agent register'.")
+
+    print_info("Retrieving agent profile...")
+    res = client.get("/v1/agents/me")
+    
+    content = (
+        f"[bold]Agent ID:[/bold] {res['id']}\n"
+        f"[bold]Name:[/bold] {res['name']}\n"
+        f"[bold]Project ID:[/bold] {res['project_id']}\n"
+        f"[bold]Capabilities:[/bold] {', '.join(res.get('capabilities', [])) or 'None'}\n"
+        f"[bold]Status:[/bold] {res.get('status', 'unknown')}\n"
+        f"[bold]Last Seen:[/bold] {res.get('last_seen_at', 'never')}\n"
+        f"[bold]Created At:[/bold] {res['created_at']}"
+    )
+    print_panel("Agent Profile", content)
+
+@agent.command("list")
+def list_agents():
+    """List all agents registered in the current project."""
+    client = AxonHttpClient()
+    if not client.api_key:
+        raise click.ClickException("No API key configured. Run 'axon init' or 'axon agent register'.")
+
+    print_info(f"Listing agents for project '{client.project_id}'...")
+    res = client.get("/v1/agents/list")
+    agents = res.get("agents", [])
+    
+    if not agents:
+        print_info("No agents found in this project.")
+        return
+
+    headers = ["ID", "Name", "Capabilities", "Status", "Last Seen"]
+    rows = []
+    for a in agents:
+        rows.append([
+            a["id"],
+            a["name"],
+            ", ".join(a.get("capabilities", [])) or "None",
+            a.get("status", "unknown"),
+            a.get("last_seen_at") or "never"
+        ])
+    
+    print_table("Project Agents", headers, rows)

axon_protocol_cli-0.1.0/axon_cli/commands/init.py

@@ -0,0 +1,30 @@
+import click
+from axon_cli.config import save_config, load_config
+from axon_cli.display import print_success, print_info
+
+@click.command()
+@click.option("--base-url", default="http://localhost:8000", help="Axon server base URL (default: http://localhost:8000)")
+@click.option("--api-key", default="", help="Agent API key")
+@click.option("--project-id", default="", help="Project ID")
+@click.option("--interactive/--no-interactive", default=True, help="Prompt interactively if not provided via options")
+def init(base_url, api_key, project_id, interactive):
+    """Initialize a new .axon configuration file in the current directory."""
+    print_info("Initializing Axon Protocol CLI...")
+    
+    current_config = load_config()
+    
+    if interactive:
+        # Prompt for base URL
+        default_url = current_config.get("base_url") or base_url
+        base_url = click.prompt("Axon server base URL", default=default_url)
+        
+        # Prompt for api key
+        default_key = current_config.get("api_key") or api_key
+        api_key = click.prompt("Agent API key (optional)", default=default_key, show_default=True)
+        
+        # Prompt for project ID
+        default_project = current_config.get("project_id") or project_id
+        project_id = click.prompt("Project ID (optional)", default=default_project, show_default=True)
+
+    config_path = save_config(base_url, api_key, project_id)
+    print_success(f"Configuration saved successfully to {config_path}")

axon_protocol_cli-0.1.0/axon_cli/commands/lock.py

@@ -0,0 +1,115 @@
+import click
+from axon_cli.http import AxonHttpClient
+from axon_cli.display import print_success, print_info, print_error, print_table, print_panel
+
+@click.group()
+def lock():
+    """Manage distributed resource locks."""
+    pass
+
+@lock.command("list")
+def list_locks():
+    """List all active locks in the project."""
+    client = AxonHttpClient()
+    if not client.api_key:
+        raise click.ClickException("No API key configured. Run 'axon init' or 'axon agent register'.")
+
+    print_info("Listing active locks...")
+    res = client.get("/v1/lock/list")
+    locks = res.get("locks", [])
+    
+    if not locks:
+        print_info("No active locks found.")
+        return
+
+    headers = ["Resource ID", "Holder Agent ID", "Locked At", "Expires At"]
+    rows = []
+    for l in locks:
+        rows.append([
+            l["resource_id"],
+            l["agent_id"],
+            l["locked_at"][:19],
+            l["expires_at"][:19]
+        ])
+        
+    print_table("Active Locks", headers, rows)
+
+@lock.command("status")
+@click.argument("resource_id")
+def status(resource_id):
+    """Check the lock status of a resource."""
+    client = AxonHttpClient()
+    if not client.api_key:
+        raise click.ClickException("No API key configured. Run 'axon init' or 'axon agent register'.")
+
+    print_info(f"Checking lock status for resource '{resource_id}'...")
+    res = client.get(f"/v1/lock/status/{resource_id}")
+    
+    locked = res.get("locked", False)
+    if locked:
+        content = (
+            f"[bold]Status:[/bold] [red]LOCKED[/red]\n"
+            f"[bold]Resource ID:[/bold] {res['resource_id']}\n"
+            f"[bold]Holder Agent ID:[/bold] {res.get('holder_agent_id')}\n"
+            f"[bold]Locked At:[/bold] {res.get('locked_at')}\n"
+            f"[bold]Expires At:[/bold] {res.get('expires_at')}"
+        )
+        print_panel("Lock Status", content, border_style="red")
+    else:
+        content = (
+            f"[bold]Status:[/bold] [green]UNLOCKED[/green]\n"
+            f"[bold]Resource ID:[/bold] {res['resource_id']}"
+        )
+        print_panel("Lock Status", content, border_style="green")
+
+@lock.command("acquire")
+@click.argument("resource_id")
+@click.option("-t", "--timeout", type=int, default=300, help="Expiration timeout in seconds (default: 300)")
+@click.option("-m", "--metadata", multiple=True, help="Optional metadata (e.g. -m owner=daemon)")
+def acquire(resource_id, timeout, metadata):
+    """Acquire an exclusive lock on a resource."""
+    client = AxonHttpClient()
+    if not client.api_key:
+        raise click.ClickException("No API key configured. Run 'axon init' or 'axon agent register'.")
+
+    meta_dict = {}
+    for item in metadata:
+        if "=" in item:
+            k, v = item.split("=", 1)
+            meta_dict[k.strip()] = v.strip()
+        else:
+            meta_dict[item.strip()] = True
+
+    payload = {
+        "resource_id": resource_id,
+        "timeout": timeout,
+    }
+    if meta_dict:
+        payload["metadata"] = meta_dict
+
+    print_info(f"Acquiring lock on resource '{resource_id}'...")
+    res = client.post("/v1/lock/acquire", json=payload)
+    
+    content = (
+        f"[bold]Lock ID:[/bold] {res['lock_id']}\n"
+        f"[bold]Resource ID:[/bold] {res['resource_id']}\n"
+        f"[bold]Expires At:[/bold] {res['expires_at']}"
+    )
+    print_panel("Lock Acquired", content)
+    print_success(f"Successfully locked resource '{resource_id}'!")
+
+@lock.command("release")
+@click.argument("resource_id")
+def release(resource_id):
+    """Release a lock on a resource."""
+    client = AxonHttpClient()
+    if not client.api_key:
+        raise click.ClickException("No API key configured. Run 'axon init' or 'axon agent register'.")
+
+    print_info(f"Releasing lock on resource '{resource_id}'...")
+    res = client.post("/v1/lock/release", params={"resource_id": resource_id})
+    
+    if res.get("released"):
+        print_success(f"Lock on resource '{resource_id}' released successfully.")
+    else:
+        print_error(f"Failed to release lock on resource '{resource_id}'.")

axon_protocol_cli-0.1.0/axon_cli/commands/memory.py

@@ -0,0 +1,129 @@
+import click
+from axon_cli.http import AxonHttpClient
+from axon_cli.display import print_success, print_info, print_table, print_panel
+
+@click.group()
+def memory():
+    """Manage vector memory storage and retrieval."""
+    pass
+
+@memory.command("store")
+@click.argument("content")
+@click.option("-t", "--tag", multiple=True, help="Custom tags to attach to the memory (e.g. -t priority=high)")
+@click.option("-s", "--scope", default="project", help="Scope of the memory (e.g. project, agent) (default: project)")
+@click.option("--ttl", type=int, help="Time to live in seconds (optional)")
+def store(content, tag, scope, ttl):
+    """Store a memory in the Axon server."""
+    client = AxonHttpClient()
+    if not client.api_key:
+        raise click.ClickException("No API key configured. Run 'axon init' or 'axon agent register'.")
+
+    tags = {}
+    for item in tag:
+        if "=" in item:
+            k, v = item.split("=", 1)
+            tags[k.strip()] = v.strip()
+        else:
+            tags[item.strip()] = True
+
+    payload = {
+        "content": content,
+        "scope": scope,
+    }
+    if tags:
+        payload["tags"] = tags
+    if ttl is not None:
+        payload["ttl"] = ttl
+
+    print_info("Storing memory...")
+    res = client.post("/v1/memory/store", json=payload)
+    
+    print_success(f"Memory stored successfully!")
+    print_info(f"ID: {res['id']}")
+    print_info(f"Created At: {res['created_at']}")
+
+@memory.command("search")
+@click.argument("query")
+@click.option("-l", "--limit", type=int, default=10, help="Max number of results (default: 10)")
+@click.option("-m", "--min-similarity", type=float, default=0.5, help="Minimum cosine similarity threshold (default: 0.5)")
+@click.option("-s", "--scope", help="Search scope filter")
+def search(query, limit, min_similarity, scope):
+    """Semantically search stored memories."""
+    client = AxonHttpClient()
+    if not client.api_key:
+        raise click.ClickException("No API key configured. Run 'axon init' or 'axon agent register'.")
+
+    payload = {
+        "query": query,
+        "limit": limit,
+        "min_similarity": min_similarity,
+    }
+    if scope:
+        payload["scope"] = scope
+
+    print_info(f"Searching memories for '{query}'...")
+    res = client.post("/v1/memory/search", json=payload)
+    results = res.get("results", [])
+    
+    if not results:
+        print_info("No matching memories found.")
+        return
+
+    headers = ["Similarity", "Content", "Tags", "Scope", "Created At"]
+    rows = []
+    for r in results:
+        tags_str = ", ".join(f"{k}={v}" for k, v in r.get("tags", {}).items()) or "None"
+        rows.append([
+            f"{r['similarity']:.4f}",
+            r["content"],
+            tags_str,
+            r["scope"],
+            r["created_at"][:19]
+        ])
+        
+    print_table(f"Search Results for '{query}'", headers, rows)
+
+@memory.command("list")
+@click.option("-l", "--limit", type=int, default=50, help="Max number of results (default: 50)")
+def list_memories(limit):
+    """List recently stored memories in the current project."""
+    client = AxonHttpClient()
+    if not client.api_key:
+        raise click.ClickException("No API key configured. Run 'axon init' or 'axon agent register'.")
+
+    print_info("Listing memories...")
+    res = client.get("/v1/memory/list", params={"limit": limit})
+    memories = res.get("memories", [])
+    
+    if not memories:
+        print_info("No memories found.")
+        return
+
+    headers = ["ID", "Content", "Tags", "Scope", "Created At"]
+    rows = []
+    for m in memories:
+        tags_str = ", ".join(f"{k}={v}" for k, v in m.get("tags", {}).items()) or "None"
+        rows.append([
+            m["id"],
+            m["content"][:60] + ("..." if len(m["content"]) > 60 else ""),
+            tags_str,
+            m["scope"],
+            m["created_at"][:19]
+        ])
+        
+    print_table("Recent Memories", headers, rows)
+
+@memory.command("delete")
+@click.argument("memory_id")
+def delete(memory_id):
+    """Delete a memory permanently by its ID."""
+    client = AxonHttpClient()
+    if not client.api_key:
+        raise click.ClickException("No API key configured. Run 'axon init' or 'axon agent register'.")
+
+    print_info(f"Deleting memory {memory_id}...")
+    res = client.delete(f"/v1/memory/{memory_id}")
+    if res.get("deleted"):
+        print_success(f"Memory {memory_id} deleted successfully.")
+    else:
+        print_error(f"Failed to delete memory {memory_id}.")

axon_protocol_cli-0.1.0/axon_cli/commands/message.py

@@ -0,0 +1,100 @@
+import click
+import json
+from axon_cli.http import AxonHttpClient
+from axon_cli.display import print_success, print_info, print_error, print_table
+
+@click.group()
+def message():
+    """Manage agent-to-agent messaging."""
+    pass
+
+@message.command("send")
+@click.argument("recipient_id", required=False)
+@click.argument("text", required=False)
+@click.option("--topic", help="Topic to publish the message to")
+@click.option("--json", "json_payload", help="JSON string payload instead of plain text")
+def send(recipient_id, text, topic, json_payload):
+    """Send a message to an agent or publish to a topic."""
+    if not recipient_id and not topic:
+        raise click.ClickException("Must specify either recipient_id or --topic.")
+        
+    client = AxonHttpClient()
+    if not client.api_key:
+        raise click.ClickException("No API key configured. Run 'axon init'.")
+        
+    # Build payload
+    payload_dict = {}
+    if json_payload:
+        try:
+            payload_dict = json.loads(json_payload)
+        except json.JSONDecodeError as e:
+            raise click.ClickException(f"Invalid JSON payload: {str(e)}")
+    elif text:
+        payload_dict = {"text": text}
+    else:
+        payload_dict = {}
+
+    req_body = {}
+    if recipient_id:
+        req_body["recipient_id"] = recipient_id
+    if topic:
+        req_body["topic"] = topic
+    req_body["payload"] = payload_dict
+
+    print_info("Sending message...")
+    res = client.post("/v1/messages/send", json=req_body)
+    
+    print_success(f"Message sent successfully! ID: {res['message_id']}, Status: {res['status']}")
+
+@message.command("inbox")
+@click.option("--topic", help="Filter inbox by topic")
+@click.option("--limit", default=50, help="Limit the number of messages to fetch")
+def inbox(topic, limit):
+    """Fetch and view unread messages in the inbox."""
+    client = AxonHttpClient()
+    if not client.api_key:
+        raise click.ClickException("No API key configured. Run 'axon init'.")
+
+    params = {"limit": limit}
+    if topic:
+        params["topic"] = topic
+
+    print_info("Fetching messages from inbox...")
+    res = client.get("/v1/messages/inbox", params=params)
+    messages = res.get("messages", [])
+
+    if not messages:
+        print_info("Inbox is empty.")
+        return
+
+    headers = ["ID", "Sender ID", "Topic", "Payload", "Status", "Created At"]
+    rows = []
+    for m in messages:
+        payload_str = str(m.get("payload", {}))
+        if len(payload_str) > 40:
+            payload_str = payload_str[:37] + "..."
+        rows.append([
+            m["id"],
+            m["sender_id"],
+            m.get("topic") or "N/A",
+            payload_str,
+            m["status"],
+            m["created_at"]
+        ])
+
+    print_table("Agent Inbox", headers, rows)
+
+@message.command("ack")
+@click.argument("message_id")
+def ack(message_id):
+    """Acknowledge a received message."""
+    client = AxonHttpClient()
+    if not client.api_key:
+        raise click.ClickException("No API key configured. Run 'axon init'.")
+
+    print_info(f"Acknowledging message {message_id}...")
+    res = client.post("/v1/messages/ack", params={"message_id": message_id})
+    if res.get("acknowledged"):
+        print_success(f"Message {message_id} acknowledged successfully.")
+    else:
+        print_error(f"Failed to acknowledge message {message_id}.")