# 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](https://github.com/astral-sh/uv) for dependency management (fast)
- Optional (local/no-keys mode): [Ollama](https://ollama.com)

### Install

```bash
uv sync
cp env.example .env
```

Edit `.env` or use the defaults:

- **Local-first (default)**: Just run [Ollama](https://ollama.com) 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

```bash
uv run albus server --debug
```

Verify:

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

### Launch terminal Studio

```bash
uv run albus studio --thread-id demo
```

---

## Building Agents

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

```python
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

```bash
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.

```python
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`:

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

Or deploy at runtime:

```bash
# 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`:

```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`
