Skip to content

AI Assistant Commands

Jump to bottom
Smithanator edited this page Jul 15, 2026 · 2 revisions

AI Assistant Commands

Relevant source files

The following files were used as context for generating this wiki page:

The Advisory Layer (Layer 5) of the AXIS architecture provides interactive, cluster-aware assistance through a suite of AI-powered commands. These surfaces consume cluster state—such as hardware facts, task history, and placement logic—to provide advisory guidance, natural language interaction, and autonomous problem-solving without ever overriding the underlying "Truth Rule" of the cluster.

Architecture Overview

The AI surfaces bridge the gap between Natural Language Space and Code Entity Space by integrating with the core AXIS subsystems.

Data Flow: Natural Language to Code Entity

The following diagram illustrates how a user prompt moves through the system to interact with specific code entities.

AI Command Execution Flow

graph TD
    User["User Prompt"] -- "axis chat / axis agent" --> CLI["cmd/axis/chat.go / cmd/axis/agent.go"]
    CLI -- "InferRequirements()" --> Inf["internal/placement/requirements.go"]
    Inf -- "Classify()" --> Router["internal/llmrouter/engine.go"]
    Router -- "SelectBestNode()" --> Placement["internal/placement/pipeline.go"]
    
    subgraph "Advisory Plane"
        CLI -- "NewConversation()" --> Conv["internal/chat/conversation.go"]
        CLI -- "NewClient()" --> Ollama["internal/chat/client.go"]
    end

    subgraph "Code Entity Space"
        Placement -- "uses" --> Snapshot["models.ClusterSnapshot"]
        Placement -- "uses" --> State["models.NodeState"]
    end

    Ollama -- "SSH Tunnel (ForwardLocal)" --> Remote["Remote Node (Ollama API)"]
Loading

Sources: cmd/axis/chat.go:81-101, cmd/axis/llm.go:57-71, internal/chat/client.go:1-20

axis chat

axis chat provides a cluster-aware REPL (Read-Eval-Print Loop) for interacting with local Large Language Models (LLMs). It features intelligent auto-routing, where inference is transparently tunneled to the most capable node in the cluster.

Key Implementation Details

  • Auto-Routing: The command uses placement.SelectBestNode to find a node capable of running the requested chat model. If the best node is remote, it establishes an SSH tunnel using executor.ForwardLocal to the remote Ollama API (typically port 11434) cmd/axis/chat.go:81-101.
  • Context Injection: It builds a ClusterSummaryForPrompt which injects a condensed version of the ClusterSnapshot into the system prompt, allowing the LLM to answer questions about cluster health and topology cmd/axis/chat.go:75-78.
  • Slash Commands: Supports in-session commands like /status, /facts, and /model to interact with the cluster or change settings without exiting the REPL cmd/axis/chat.go:52-58.

Model Resolution

AXIS maintains a hierarchy for selecting models:

  1. Explicit Flag: --model override.
  2. Configuration: chat.default_model in nodes.yaml.
  3. Discovery: chat.ResolveDefaultModel probes the local Ollama instance for installed models and matches them against recommendedLocalModels (e.g., qwen3.5:4b, llama3.1:8b) internal/chat/models.go:52-60, internal/chat/models.go:30-37.

Sources: cmd/axis/chat.go:33-101, internal/chat/models.go:1-60

axis agent

The axis agent command initializes an autonomous agent.Agent capable of tool-calling. Unlike chat, the agent can execute read-only queries and guarded shell commands to fulfill complex instructions.

Tool Registry and Safety

The agent uses a ToolRegistry to interact with the cluster. Shell/cluster tools (run_shell, run_on_node, axis_run_task, remote run_background) go through Layer-4 RunGuarded after agent confirmation; file mutations use agent confirmation and a CWD path sandbox. When present, the nearest AGENTS.md is injected into the system prompt as repository instructions.

Tool Category Code Entity / Package Purpose
Cluster Facts internal/knowledge Access hardware telemetry and node status.
Placement internal/placement Explain why a task would run on a specific node.
Persistence internal/chat Load/Save conversation history.
External internal/mcpclient Connect to third-party Model Context Protocol servers.

Sources: cmd/axis/agent.go:128-172, cmd/axis/agent.go:174-185

axis llm

The axis llm command is the entry point for the Semantic Router. It classifies a natural language prompt into a WorkloadClass and derives hardware requirements (TaskRequirements) for the placement engine.

Classification Logic

The command uses the llmrouter.Engine to perform classification cmd/axis/llm.go:122-131.

  1. Semantic Mode: Uses a local lightweight model (default: granite3.1-moe:1b) to parse intent cmd/axis/llm.go:107-108.
  2. Reflex Mode: If the LLM is unreachable or times out (default 150ms), it falls back to a deterministic string-matching "reflex" engine cmd/axis/llm.go:113-114, cmd/axis/llm.go:175.
  3. Cloud Fallback: If configured, AXIS can prompt the user to use a cloud provider (e.g., OpenAI, Anthropic) if local classification fails cmd/axis/llm.go:141.

Sources: cmd/axis/llm.go:93-183, cmd/axis/llm.go:57-71

axis cortex (Experimental)

axis cortex interacts with the Cortex Cluster Brain, an optional coordination layer typically hosted on a node named "foundry" cmd/axis/cortex.go:21-28.

Features and Implementation

Cortex Integration Architecture

graph LR
    subgraph "AXIS Node"
        Cmd["axis cortex"] -- "JSON-RPC 2.0" --> Client["internal/cortex/Client"]
    end

    subgraph "Foundry Node (Cortex)"
        Client -- "Port 8200" --> MCPServer["Cortex MCP Server"]
        MCPServer -- "Recall" --> Qdrant["Qdrant (Port 6333)"]
        MCPServer -- "Events" --> Bus["Event Store"]
        MCPServer -- "Locking" --> Lock["Lock Manager"]
    end
Loading

Sources: internal/cortex/client.go:22-62, cmd/axis/cortex.go:44-64

axis mcp

The axis mcp command group allows AXIS to act as either an MCP (Model Context Protocol) server or client.

  • axis mcp serve: Exposes AXIS cluster primitives (snapshot, placement, execution) as tools to external AI editors (like Claude Desktop or Cursor) cmd/axis/command_surface_test.go:137-154.
  • Client Integration: The axis agent can connect to external MCP servers defined in nodes.yaml to extend its own capabilities (e.g., connecting to a GitHub or Google Maps MCP) cmd/axis/agent.go:174-185.

Sources: cmd/axis/command_surface_test.go:54, cmd/axis/agent.go:174-185

AXIS Wiki

Architecture Artifacts

DeepWiki

Clone this wiki locally