albusos 0.4.0__tar.gz

albusos-0.4.0/PKG-INFO

@@ -0,0 +1,341 @@
+Metadata-Version: 2.4
+Name: albusos
+Version: 0.4.0
+Summary: Albus AgentOS - Event-driven AI agent runtime
+Author: Your Name
+Author-email: Your Name <your.email@example.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: pydantic>=2.0,<3
+Requires-Dist: aiohttp>=3.9,<4
+Requires-Dist: ddgs>=9.0,<10
+Requires-Dist: idna>=3.6,<4
+Requires-Dist: openai>=1.0,<2
+Requires-Dist: anthropic>=0.20,<0.21
+Requires-Dist: python-dotenv>=1.0,<2
+Requires-Dist: aiostream>=0.6.4,<0.7
+Requires-Dist: pyyaml>=6.0.3,<7
+Requires-Dist: mcp>=1.0,<2
+Requires-Dist: google-generativeai>=0.5,<0.6 ; extra == 'all'
+Requires-Dist: google-generativeai>=0.5,<0.6 ; extra == 'google'
+Requires-Python: >=3.11, <4
+Provides-Extra: all
+Provides-Extra: google
+Description-Content-Type: text/markdown
+
+# 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`

albusos-0.4.0/README.md

@@ -0,0 +1,312 @@
+# 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`