xyberos 0.4.2__py3-none-any.whl

xyberos/__init__.py

@@ -0,0 +1,74 @@
+"""
+XYBEROS Platform - Cognitive Operating System.
+
+The public API surface.  Anything not re-exported from ``xyberos`` or a
+direct child package (``xyberos.tools``, ``xyberos.agents``, etc.) is
+considered internal.
+
+Usage::
+
+    from xyberos import xyberos
+
+    ctx = xyberos.chat("Hello world")
+    result = xyberos.reason("If A > B, what follows?")
+    steps = xyberos.plan("Build a house")
+    memories = xyberos.remember("past conversations")
+
+    # Or use the functional API directly:
+    from xyberos.api import chat, reason, plan, remember
+
+    ctx = chat("Hello world")
+
+Configuration::
+
+    from xyberos import xyberos, XyberosConfig
+
+    config = XyberosConfig(llm_backend="ollama", llm_model="llama3")
+    platform = xyberos.__class__(config=config)
+    ctx = platform.chat("Hello")
+
+    # Or configure the global instance:
+    xyberos.configure(config)
+
+Tools::
+
+    from xyberos.tools import ToolManager, WebSearchTool
+    from xyberos.agents import Agent, AgentManager
+    from xyberos.skills import Skill, SkillManager
+    from xyberos.memory import MemoryManager
+    from xyberos.knowledge import KnowledgeManager
+"""
+
+from __future__ import annotations
+
+# ── High-level facade ──────────────────────────────────────────
+from xyberos.assistant import XYBEROS
+
+# ── API functions ──────────────────────────────────────────────
+from xyberos.api import chat, reason, plan, remember, forget, store, execute
+
+# ── Config ─────────────────────────────────────────────────────
+from xyberos.config import XyberosConfig
+
+# ── Global singleton instance ──────────────────────────────────
+xyberos: XYBEROS = XYBEROS()
+
+# ── Backward compatibility alias ───────────────────────────────
+Assistant = XYBEROS
+
+__all__ = [
+    # High-level
+    "XYBEROS",
+    "xyberos",
+    "Assistant",
+    "XyberosConfig",
+    # API functions
+    "chat",
+    "reason",
+    "plan",
+    "remember",
+    "forget",
+    "store",
+    "execute",
+]
+

xyberos/agents/__init__.py

@@ -0,0 +1,33 @@
+"""Multi-Agent Runtime — agents with communication, shared memory, and collaboration."""
+
+from __future__ import annotations
+
+from .agent import Agent
+from .collaboration import CollaborationEngine, Vote, VoteResult
+from .context import AgentContext
+from .lifecycle import AgentState
+from .manager import AgentManager
+from .message_bus import Message, MessageBus
+from .plugin import AgentPlugin
+from .registry import AgentRegistry
+from .shared_memory import SharedMemory, SharedEntry
+from .task import Task, TaskManager, TaskStatus
+
+__all__ = [
+    "Agent",
+    "AgentContext",
+    "AgentManager",
+    "AgentPlugin",
+    "AgentRegistry",
+    "AgentState",
+    "CollaborationEngine",
+    "Message",
+    "MessageBus",
+    "SharedEntry",
+    "SharedMemory",
+    "Task",
+    "TaskManager",
+    "TaskStatus",
+    "Vote",
+    "VoteResult",
+]

xyberos/agents/agent.py

@@ -0,0 +1,187 @@
+"""Base Agent class with communication, shared memory, and collaboration."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from .message_bus import Message, MessageBus
+
+if TYPE_CHECKING:
+    from .shared_memory import SharedMemory
+    from .collaboration import CollaborationEngine
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(slots=True)
+class Agent:
+    """
+    Base runtime agent with inter-agent communication, shared memory,
+    and collaborative intelligence.
+
+    Agents can:
+        - Send/receive messages via the shared :class:`MessageBus`
+        - Read/write to shared memory via :attr:`shared_memory`
+        - Collaborate via :attr:`collaboration`
+          (voting, knowledge sharing, collective problem solving)
+
+    Specialized agents extend this class and override :meth:`handle_message`.
+
+    Usage::
+
+        class ResearcherAgent(Agent):
+            async def handle_message(self, msg):
+                # Access shared memory
+                await self.shared_memory.store("finding:x", value, agent_id=self.id)
+                # Collaborate with other agents
+                result = await self.collaboration.conduct_vote(...)
+    """
+
+    id: str
+    name: str
+    description: str = ""
+    metadata: dict[str, Any] = field(default_factory=lambda: {})
+
+    # Communication (set by AgentManager on registration)
+    _bus: MessageBus | None = None
+    _queue: asyncio.Queue[Message] | None = None
+    _running: bool = False
+    _shared_memory: Any = None  # SharedMemory
+    _collaboration: Any = None  # CollaborationEngine
+
+    # ── Shared Memory ──────────────────────────────────────────
+
+    @property
+    def shared_memory(self) -> SharedMemory:
+        """Access the shared memory space shared by all agents."""
+        if self._shared_memory is None:
+            raise RuntimeError(
+                f"Agent '{self.id}' is not connected to shared memory. "
+                "Ensure it is registered via AgentManager."
+            )
+        return self._shared_memory
+
+    @property
+    def collaboration(self) -> CollaborationEngine:
+        """Access the collaboration engine for voting and collective problem solving."""
+        if self._collaboration is None:
+            raise RuntimeError(
+                f"Agent '{self.id}' is not connected to collaboration engine. "
+                "Ensure it is registered via AgentManager."
+            )
+        return self._collaboration
+
+    # ── Lifecycle ──────────────────────────────────────────────
+
+    async def start(self) -> None:
+        """Called when the agent starts. Subscribes to the message bus."""
+        self._running = True
+        if self._bus:
+            self._queue = await self._bus.subscribe(self.id)
+            asyncio.create_task(self._message_loop())
+        logger.info("Agent '%s' (%s) started", self.name, self.id)
+
+    async def stop(self) -> None:
+        """Called when the agent stops."""
+        self._running = False
+        if self._bus:
+            await self._bus.unsubscribe(self.id)
+        logger.info("Agent '%s' (%s) stopped", self.name, self.id)
+
+    # ── Communication ──────────────────────────────────────────
+
+    async def send_message(
+        self,
+        receiver: str,
+        content: Any,
+        *,
+        msg_type: str = "message",
+        correlation_id: str = "",
+    ) -> None:
+        """Send a message to another agent."""
+        if not self._bus:
+            logger.warning("Agent '%s': not connected to message bus", self.id)
+            return
+        msg = Message(
+            sender=self.id,
+            receiver=receiver,
+            content=content,
+            msg_type=msg_type,
+            correlation_id=correlation_id,
+        )
+        await self._bus.send(msg)
+
+    async def broadcast(self, content: Any, *, msg_type: str = "broadcast") -> None:
+        """Broadcast a message to all agents."""
+        await self.send_message("*", content, msg_type=msg_type)
+
+    async def request(
+        self,
+        receiver: str,
+        content: Any,
+        *,
+        timeout: float = 10.0,
+    ) -> Message | None:
+        """Send a request and wait for a reply."""
+        if not self._bus:
+            return None
+        return await self._bus.request(self.id, receiver, content, timeout=timeout)
+
+    async def reply_to(self, original: Message, content: Any) -> None:
+        """Reply to an incoming request message."""
+        if self._bus:
+            await self._bus.reply(original, content)
+
+    # ── Collaborative Intelligence ─────────────────────────────
+
+    async def share_knowledge(
+        self,
+        topic: str,
+        content: Any,
+        *,
+        tags: list[str] | None = None,
+    ) -> None:
+        """Share knowledge on a *topic* with all agents via shared memory."""
+        if self._collaboration:
+            await self._collaboration.share_knowledge(self, topic, content, tags=tags)
+
+    async def query_knowledge(self, topic: str, *, limit: int = 10) -> list[Any]:
+        """Query shared knowledge on a *topic* from all agents."""
+        if self._collaboration:
+            return await self._collaboration.query_knowledge(topic, limit=limit)
+        return []
+
+    async def vote_on(
+        self,
+        question: str,
+        agents: list[Agent],
+        options: list[str],
+    ) -> Any:
+        """Conduct a vote among *agents* on a *question*."""
+        if self._collaboration:
+            return await self._collaboration.conduct_vote(question, agents, options)
+        return None
+
+    # ── Message Handling ───────────────────────────────────────
+
+    async def handle_message(self, message: Message) -> None:
+        """
+        Handle an incoming message. Override in subclasses.
+
+        Default behavior: log the message.
+        """
+        logger.info("Agent '%s' received: %s", self.id, str(message.content)[:100])
+
+    async def _message_loop(self) -> None:
+        """Continuously process incoming messages."""
+        while self._running and self._queue is not None:
+            try:
+                message = await asyncio.wait_for(self._queue.get(), timeout=1.0)
+                await self.handle_message(message)
+            except asyncio.TimeoutError:
+                continue
+            except Exception as exc:
+                logger.error("Agent '%s' message handler error: %s", self.id, exc)

xyberos/agents/builtins.py

@@ -0,0 +1,203 @@
+"""Built-in specialized agents for the multi-agent runtime."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, cast
+
+from .agent import Agent
+from .message_bus import Message
+from .task import Task, TaskManager, TaskStatus
+
+logger = logging.getLogger(__name__)
+
+
+class PlannerAgent(Agent):
+    """
+    Receives goals, breaks them into sub-tasks, and delegates to agents.
+
+    The planner analyzes a goal description, creates a list of tasks
+    with dependencies, assigns them to appropriate agents, and tracks
+    completion.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(
+            id="planner",
+            name="Planner",
+            description="Breaks goals into sub-tasks and delegates to agents",
+        )
+        self._task_manager = TaskManager()
+
+    @property
+    def task_manager(self) -> TaskManager:
+        return self._task_manager
+
+    async def handle_message(self, message: Message) -> None:
+        if message.msg_type == "plan_goal":
+            await self._plan_goal(message)
+        elif message.msg_type == "task_completed":
+            await self._on_task_completed(message)
+        elif message.msg_type == "task_failed":
+            await self._on_task_failed(message)
+
+    async def _plan_goal(self, message: Message) -> None:
+        """Receive a goal, create tasks, delegate."""
+        goal = str(message.content)
+        # Create sub-tasks from the goal
+        tasks = [
+            Task(id="research", description=f"Research: {goal}", priority=1),
+            Task(id="execute", description=f"Execute: {goal}", depends_on=["research"], priority=2),
+            Task(id="review", description=f"Review results for: {goal}", depends_on=["execute"], priority=3),
+        ]
+        for t in tasks:
+            self._task_manager.add(t)
+
+        # Assign ready tasks to agents
+        for task in self._task_manager.ready():
+            agent_id = self._select_agent(task)
+            if agent_id:
+                self._task_manager.assign(task.id, agent_id)
+                await self.send_message(agent_id, {
+                    "task_id": task.id,
+                    "description": task.description,
+                    "goal": goal,
+                }, msg_type="execute_task")
+
+        await self.reply_to(message, {
+            "status": "planned",
+            "tasks": len(tasks),
+            "ready": len(self._task_manager.ready()),
+        })
+
+    async def _on_task_completed(self, message: Message) -> None:
+        """Handle a task completion notification."""
+        raw = message.content
+        data: dict[str, Any] = cast(dict[str, Any], raw) if isinstance(raw, dict) else {}
+        task_id = data.get("task_id", "")
+        self._task_manager.update_status(task_id, TaskStatus.COMPLETED)
+
+        # Check for newly ready tasks
+        for task in self._task_manager.ready():
+            agent_id = self._select_agent(task)
+            if agent_id:
+                self._task_manager.assign(task.id, agent_id)
+                await self.send_message(agent_id, {
+                    "task_id": task.id,
+                    "description": task.description,
+                }, msg_type="execute_task")
+
+    async def _on_task_failed(self, message: Message) -> None:
+        """Handle a task failure."""
+        raw = message.content
+        data: dict[str, Any] = cast(dict[str, Any], raw) if isinstance(raw, dict) else {}
+        task_id = data.get("task_id", "")
+        self._task_manager.update_status(task_id, TaskStatus.FAILED)
+
+    def _select_agent(self, task: Task) -> str | None:
+        """Select an agent to handle a task based on task description."""
+        desc_lower = task.description.lower()
+        if "research" in desc_lower or "search" in desc_lower:
+            return "researcher"
+        if "review" in desc_lower or "verify" in desc_lower:
+            return "reviewer"
+        if "execute" in desc_lower or "run" in desc_lower:
+            return "executor"
+        return "executor"
+
+
+class ResearcherAgent(Agent):
+    """
+    Queries knowledge, memory, and web for information.
+
+    Responds to "research" or "search" tasks by querying available
+    knowledge sources via the KnowledgeManager.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(
+            id="researcher",
+            name="Researcher",
+            description="Queries knowledge, memory, and web for information",
+        )
+
+    async def handle_message(self, message: Message) -> None:
+        if message.msg_type == "execute_task":
+            raw = message.content
+            data: dict[str, Any] = cast(dict[str, Any], raw) if isinstance(raw, dict) else {}
+            task_id = data.get("task_id", "")
+            description = data.get("description", "")
+
+            # Simulate research
+            result = f"Research results for: {description[:100]}"
+
+            await self.send_message("planner", {
+                "task_id": task_id,
+                "result": result,
+            }, msg_type="task_completed")
+
+
+class ReviewerAgent(Agent):
+    """
+    Reviews plans and results for quality, safety, and consistency.
+
+    Responds to "review" tasks by evaluating the provided content
+    against quality criteria.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(
+            id="reviewer",
+            name="Reviewer",
+            description="Reviews plans and results for quality and safety",
+        )
+
+    async def handle_message(self, message: Message) -> None:
+        if message.msg_type == "execute_task":
+            raw = message.content
+            data: dict[str, Any] = cast(dict[str, Any], raw) if isinstance(raw, dict) else {}
+            task_id = data.get("task_id", "")
+            description = data.get("description", "")
+
+            # Simulate review
+            result = f"Review approved for: {description[:100]}"
+
+            await self.send_message("planner", {
+                "task_id": task_id,
+                "result": result,
+                "approved": True,
+            }, msg_type="task_completed")
+
+
+class ExecutorAgent(Agent):
+    """
+    Executes actions via the ActionExecutor.
+
+    Responds to "execute" tasks by running the described action
+    through the ActionExecutor.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(
+            id="executor",
+            name="Executor",
+            description="Executes actions via ActionExecutor",
+        )
+        self._executor: Any = None
+
+    async def handle_message(self, message: Message) -> None:
+        if message.msg_type == "execute_task":
+            raw = message.content
+            data: dict[str, Any] = cast(dict[str, Any], raw) if isinstance(raw, dict) else {}
+            task_id = data.get("task_id", "")
+            description = data.get("description", "")
+
+            # Try to execute via ActionExecutor
+            result = f"Executed: {description[:100]}"
+            success = True
+
+            await self.send_message("planner", {
+                "task_id": task_id,
+                "result": result,
+                "success": success,
+            }, msg_type="task_completed" if success else "task_failed")