albusos 0.4.0

Albus AgentOS - Event-driven AI agent runtime

AlbusOS

AlbusOS is an event-driven AI agent runtime.

Core Abstractions

Agent → Skills → Pathways → Nodes
Pack  → Pathways → Nodes (deployment bundles)

• Agent: Persistent AI entity with identity, memory, skills, and goals
• Skill: Pathway wrapped as an agent capability
• Pack: Deployable unit with pathways, triggers, and tool requirements
• Pathway: Execution graph (nodes + connections)
• Node: Atomic compute unit (LLM, Tool, Transform, AgentLoop, etc.)
• Trigger: Event source that invokes a pathway (webhook, timer, MCP)

---

Quickstart (local dev)

Prereqs

• Python 3.13+
• uv for dependency management (fast)
• Optional (local/no-keys mode): Ollama

Install

uv sync
cp env.example .env

Edit .env or use the defaults:

• Local-first (default): Just run Ollama with qwen2.5:7b and llama3.1:8b
• Cloud fallback: Set OPENAI_API_KEY for vision/speech capabilities

The system is local-first by default—no cloud API keys required for basic operation.

Run the server

uv run albus server --debug

Verify:

curl http://127.0.0.1:8080/api/v1/health

Launch terminal Studio

uv run albus studio --thread-id demo

---

Building Agents

Agents are persistent AI entities with identity, memory, and skills. Skills wrap pathways as capabilities.

from pathway_engine.domain.agent.builder import agent_builder
from pathway_engine.domain.agent.skill import skill_builder
from agents.registry import agent
from packs.research.pathways import build_deep_analysis_pathway

# Wrap a pathway as a skill
research_skill = (
    skill_builder()
    .id("deep_research")
    .name("Deep Research")
    .description("In-depth research using web search and synthesis")
    .pathway(build_deep_analysis_pathway)
    .input("query", "string - the research topic")
    .output("response", "string - synthesized findings")
    .build()
)

# Create the agent
@agent
def RESEARCH_ASSISTANT():
    return (
        agent_builder()
        .id("research_assistant")
        .name("Research Assistant")
        .persona("You are a thorough research assistant who cites sources.")
        .goal("Find accurate information")
        .goal("Synthesize findings clearly")
        .skill(research_skill)
        .tool("web.*")
        .tool("memory.*")
        .as_reasoning_agent()
        .max_steps(15)
        .build()
    )

Running an Agent Turn

curl -X POST http://localhost:8080/api/v1/agents/research_assistant/turn \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Research quantum computing developments in 2024",
    "thread_id": "conv_123"
  }'

See src/agents/README.md for full documentation.

---

Building Packs

Packs are deployable bundles of pathways and triggers.

from pathway_engine import pack_builder, Pack, Pathway, LLMNode
from packs.registry import deployable

@deployable
def MY_PACK():
    """Define and register a pack."""
    return (
        pack_builder()
        .id("my_pack")
        .name("My Pack")
        .version("1.0.0")
        .trigger(
            id="on_request",
            source="webhook",
            pathway="my_pack.respond.v1",
        )
        .pathway("my_pack.respond.v1", build_respond_pathway)
        .build()
    )

def build_respond_pathway() -> Pathway:
    """Build the main pathway."""
    return Pathway(
        id="my_pack.respond.v1",
        nodes={
            "respond": LLMNode(
                id="respond",
                prompt="You are helpful. Respond to: {{message}}",
                model="auto",
            ),
        },
    )

Deploying Packs and Agents

Configure in albus.yaml:

packs: ["*"]   # Deploy all registered packs
agents: ["*"]  # Deploy all registered agents

Or deploy at runtime:

# Deploy packs
curl -X POST http://localhost:8080/api/v1/packs/deploy \
  -H "Content-Type: application/json" \
  -d '{"pack_ids": ["research"]}'

# Deploy agents
curl -X POST http://localhost:8080/api/v1/agents/deploy \
  -H "Content-Type: application/json" \
  -d '{"agent_ids": ["research_assistant"]}'

---

Model Routing (Local-First)

AlbusOS automatically routes tasks to the best model:

Task	Default Model	Provider
Tool calling	qwen2.5:7b	Ollama
Code generation	qwen2.5-coder:7b	Ollama
Reasoning	llama3.1:8b	Ollama
Vision	gpt-4o	OpenAI (fallback)

Configure via albus.yaml:

models:
  default_profile: local
  routing:
    tool_calling: qwen2.5:7b
    code: qwen2.5-coder:7b
    reasoning: llama3.1:8b

---

API Surface

The server is versioned under /api/v1:

Core Endpoints

• GET /api/v1/health - Health check
• GET /api/v1/help - Detailed endpoint help
• GET /api/v1/tools - List available tools
• GET /api/v1/docs - Swagger UI

Agent API

• GET /api/v1/agents - List available agents
• GET /api/v1/agents/deployed - List deployed agents
• POST /api/v1/agents/deploy - Deploy agents
• GET /api/v1/agents/{id} - Get agent details
• POST /api/v1/agents/{id}/turn - Run an agent turn

Pack API

• GET /api/v1/packs - List available packs
• GET /api/v1/packs/deployed - List deployed packs
• POST /api/v1/packs/deploy - Deploy packs

Pathway API

• GET /api/v1/pathways - List pathways
• POST /api/v1/pathways - Create pathway
• POST /api/v1/pathways/{id}/run - Run a pathway
• GET /api/v1/pathways/{id}/export - Export pathway

Real-time

• GET /api/v1/ws - WebSocket (events + JSON-RPC)
• POST /api/v1/webhooks/{topic} - Trigger webhook event

Model Config

• GET /api/v1/config/models - View routing config
• PATCH /api/v1/config/models - Update routing

---

Code Execution + Sandboxing

AlbusOS supports sandboxed Python execution:

• Tool: code.execute (stdlib tool)
• Isolation: Docker (default) or local (dev-only)

Configure via env vars:

• AGENT_STDLIB_CODE_SANDBOX_MODE: docker (default) or local
• AGENT_STDLIB_CODE_SANDBOX_DOCKER_IMAGE: default image

---

Architecture

shared_types (bottom)
    ↑
pathway_engine (runtime kernel + agent domain)
    ↑
stdlib (tools + LLM routing)
    ↑
persistence (storage)
    ↑
packs (deployable pathway bundles)
    ↑
agents (persistent AI entities)
    ↑
albus (top — product runtime + transports)

See docs/ARCHITECTURE.md for details.

---

Available Agents

Agent	Description	Skills
research_assistant	Thorough research with source citation	deep_research, quick_search

Available Packs

Pack	Description	Pathways
quickstart	Minimal demo	1
research	Web search + analysis	2
viz	Diagram generation	1
dataanalysis	ML-powered analysis	6
timesheet	Timesheet extraction	1
ontology	Ontology extraction	1

---

Contributing

• docs/DEVELOPMENT.md
• docs/ARCHITECTURE.md
• src/agents/README.md
• src/packs/README.md
• CONTRIBUTING.md