XYBEROS API & SDK Reference

The XYBEROS Platform exposes a layered API surface for developers. You can use the high-level façade (xyberos singleton), the functional API (xyberos.api), or import sub-packages directly for more control.

1. Quick Start

from xyberos import xyberos

# Run the full cognitive pipeline
ctx = xyberos.chat("What is the capital of France?")
print(ctx.thought.summary)
print(ctx.action.metadata)

# Direct reasoning
result = xyberos.reason("If A > B and B > C, what follows?")
print(result)  # "A > C"

# Generate a plan
steps = xyberos.plan("Build a web application")
for i, step in enumerate(steps, 1):
    print(f"  Step {i}: {step}")

# Memory operations
xyberos.store_memory("greeting", "Hello, world!", tier="working")
memories = xyberos.remember("greeting")
print(memories)

# Execute an action
from xyberos.api import execute
result = execute("calculator", expression="2 + 2")
print(result.value)  # 4

2. Top-Level API (`xyberos`)

from xyberos import xyberos, XYBEROS, XyberosConfig, Assistant
from xyberos import chat, reason, plan, remember, forget, store, execute

`XYBEROS` class

The XYBEROS class is the unified façade for the entire cognitive platform. A global singleton is pre-created as xyberos.

platform = XYBEROS()                          # defaults
platform = XYBEROS(config=XyberosConfig(...))  # custom config

Method	Returns	Description
`chat(message)`	`CognitiveContext`	Full cognitive pipeline (perceive → reason → plan → decide → act)
`achat(message)`	`CognitiveContext`	Async variant — runs `chat` in a thread pool
`reason(observation, context="", strategy=None)`	`str`	Direct reasoning without the full loop
`plan(goal_description)`	`list[str]`	Generate ordered plan steps
`remember(query, limit=5)`	`list[str]`	Retrieve memories across all tiers
`store_memory(key, content, tier="working", **metadata)`	`None`	Store a value in a memory tier
`execute(action_name, **params)`	`Any`	Execute a registered action
`configure(config)`	`None`	Reconfigure (resets all subsystems)

Properties

Property	Type	Description
`brain`	`Brain`	The cognitive engine (lazy)
`memory`	`MemoryManager`	Multi-tier memory manager (lazy)
`reasoning`	`CognitiveReasoningEngine`	Reasoning engine with strategies (lazy)

Example — Full cycle with result inspection

from xyberos import xyberos

ctx = xyberos.chat("What is 2 + 2?")

print(ctx.observation.content)   # "What is 2 + 2?"
print(ctx.thought.summary)       # "The user asks about arithmetic"
print(ctx.goal.description)      # "Answer the user's question"
print(ctx.plan.steps)            # ["Compute 2+2", "Return result"]
print(ctx.decision.selected)     # "compute"
print(ctx.action.name)           # "calculator"
print(ctx.action.metadata)       # {"expression": "2+2", "result": 4}

3. Functional API (`xyberos.api`)

from xyberos.api import chat, achat, reason, plan, remember, forget, store, execute

These functions operate on the global XYBEROS singleton and are the simplest way to get started.

Function	Signature	Description
`chat`	`(text) -> CognitiveContext`	Full cognitive cycle
`achat`	`(text) -> CognitiveContext`	Async full cycle
`reason`	`(observation, context="", strategy=None) -> str`	Direct reasoning
`plan`	`(goal_description) -> list[str]`	Generate a plan
`remember`	`(query, limit=5) -> list[str]`	Retrieve memories
`forget`	`(key, tier="working") -> bool`	Delete a memory
`store`	`(key, content, tier="working", **metadata)`	Store in memory
`execute`	`(action_name, **params) -> Any`	Execute an action

Example — Functional style

from xyberos.api import chat, reason, plan, remember, store, execute

# Chat
ctx = chat("Hello!")
print(ctx.observation.content)

# Reason
answer = reason("What follows from all men being mortal?")
print(answer)

# Plan
steps = plan("Organize a team meeting")
print(steps)

# Memory
store("user_name", "Alice", tier="working")
results = remember("user_name")
print(results)  # ["Alice"]

# Action
result = execute("web_search", query="latest AI news")
print(result.value)

4. Configuration (`xyberos.config`)

from xyberos.config import XyberosConfig

XyberosConfig uses layered resolution:

Hard-coded dataclass defaults
YAML file (config.xyberos.yaml auto-discovered)
Environment variables (XYBEROS_*)
Programmatic overrides

# Zero-config — all defaults
config = XyberosConfig()

# Auto-detect YAML + env vars
config = XyberosConfig.load()

# Programmatic overrides
config = XyberosConfig(
    llm_backend="ollama",
    llm_model="llama3",
    llm_base_url="http://localhost:11434",
)

# Apply to the global instance
from xyberos import xyberos
xyberos.configure(config)

# Or create a dedicated instance
from xyberos import XYBEROS
platform = XYBEROS(config=config)

Key configuration fields:

Field	Default	Description
`llm_backend`	`"simulated"`	LLM backend (`"ollama"`, `"openai"`, `"anthropic"`, `"simulated"`)
`llm_model`	`"llama3"`	Model name
`llm_base_url`	`""`	Custom API base URL
`llm_api_key`	`""`	API key (or set `LLM_API_KEY` env var)
`safety_config_path`	`""`	Path to safety rules YAML
`database_url`	`""`	Database connection string

5. Tools (`xyberos.tools`)

from xyberos.tools import (
    Tool, ToolManager, ToolRegistry,
    ToolInput, ToolResult, ToolSpec,
    WebSearchTool, ReadFileTool, CalculatorTool, ListDirectoryTool,
)

ToolManager

from xyberos.tools import ToolManager, CalculatorTool, WebSearchTool

manager = ToolManager()

# Tools are auto-discovered from entry points, or register manually:
manager.register("calc", CalculatorTool())
manager.register("search", WebSearchTool())

# Execute
result = manager.run("calc", expression="sqrt(144)")
print(result.value)   # 12.0
print(result.success)  # True

# List all registered tools
all_tools = manager.list_tools()
for name, tool in all_tools.items():
    print(f"  {name}: {tool.description}")

Built-in tools

Tool	Method	Description
`WebSearchTool`	`run(query, max_results=5)`	Web search
`ReadFileTool`	`run(path, encoding="utf-8")`	Read file contents
`CalculatorTool`	`run(expression)`	Safe math evaluation
`ListDirectoryTool`	`run(path=".")`	List directory contents

Creating custom tools

from xyberos.tools import Tool
from xyberos.tools.models import ToolResult

class GreetingTool(Tool):
    @property
    def name(self) -> str:
        return "greeting"

    @property
    def description(self) -> str:
        return "Return a friendly greeting."

    def run(self, name: str = "World") -> ToolResult:  # type: ignore[override]
        return ToolResult.ok(value=f"Hello, {name}!")

# Register and use
manager.register("greet", GreetingTool())
result = manager.run("greet", name="Alice")
print(result.value)  # "Hello, Alice!"

6. Agents (`xyberos.agents`)

from xyberos.agents import (
    Agent, AgentManager, AgentRegistry, AgentContext, AgentState,
    Message, MessageBus,
    CollaborationEngine, Vote, VoteResult,
    SharedMemory, SharedEntry,
    Task, TaskManager, TaskStatus,
)

Creating an agent

from xyberos.agents import Agent

class MyAgent(Agent):
    def __init__(self) -> None:
        super().__init__(
            id="my_agent",
            name="My Agent",
            description="A custom agent",
        )

    async def handle_message(self, message: Message) -> None:
        print(f"Received: {message.content}")
        await self.reply_to(message, {"status": "done"})

AgentManager

from xyberos.agents import AgentManager

manager = AgentManager()
manager.register(MyAgent())
manager.start()

await manager.send_message("my_agent", {"task": "hello"})
await manager.broadcast({"announcement": "System update"})

Collaboration

from xyberos.agents import CollaborationEngine, SharedMemory

memory = SharedMemory()
engine = CollaborationEngine(shared_memory=memory)

# Vote among agents
result = await engine.conduct_vote(
    question="Best approach?",
    agents=[agent_a, agent_b],
    options=["approach_a", "approach_b"],
)
print(f"Winner: {result.winner} (consensus: {result.consensus})")

# Collective problem solving
merged = await engine.solve_collectively(
    problem="Design a microservice architecture",
    coordinator=planner_agent,
    agents=[agent_a, agent_b, agent_c],
)

7. Skills (`xyberos.skills`)

from xyberos.skills import Skill, SkillManager, SkillRegistry, SkillLoader, SkillManifest

from xyberos.skills import Skill

class MySkill(Skill):
    @property
    def name(self) -> str:
        return "my_skill"

    async def execute(self, **kwargs) -> Any:
        return f"Executed with {kwargs}"

8. Memory (`xyberos.memory`)

from xyberos.memory import (
    MemoryManager, MemoryRegistry,
    MemoryItem, MemoryQuery, MemoryResult,
    IMemoryStore, IRetrievalStrategy,
    WorkingMemoryProvider, EpisodicMemoryProvider,
    SemanticMemoryProvider, VectorMemoryProvider,
)

MemoryManager

from xyberos.memory import MemoryManager, MemoryItem, MemoryQuery

mm = MemoryManager()
mm.register_defaults()

# Store
mm.store(MemoryItem(key="note1", content="Buy groceries"), tier="working")

# Query
result = mm.query(MemoryQuery(text="groceries", limit=5))
for item in result.items:
    print(f"  [{result.tier}] {item.content}")

# Delete
mm.delete("note1")

Tier fallback chain

working → episodic → semantic → procedural → vector → knowledge_graph

9. Knowledge (`xyberos.knowledge`)

from xyberos.knowledge import (
    KnowledgeManager, KnowledgeProviderRegistry,
    Chunker, CitationGenerator, EmbeddingModel,
    GroundingEngine, KnowledgeFusion, KnowledgeIndex,
    KnowledgeRanker, KnowledgeReranker, RetrievalStrategy,
)

from xyberos.knowledge import KnowledgeManager

km = KnowledgeManager()
km.register_defaults()

# Store knowledge
km.store("topic:ai", "Artificial Intelligence is...")

# Retrieve
results = km.retrieve("What is AI?")
for r in results:
    print(r.content)

10. REST API (`xyberos.server`)

Start the server:

python -m xyberos.server.app
# or
uvicorn xyberos.server.app:app --host 0.0.0.0 --port 8080

Endpoints

Method	Path	Description
POST	`/chat`	Full cognitive cycle (supports SSE streaming)
POST	`/reason`	Direct reasoning
POST	`/plan`	Generate a plan
POST	`/memory`	Store/query memories
POST	`/action`	Execute an action
GET	`/tools`	List registered tools
GET	`/health`	Health check

Example — curl

curl -X POST http://localhost:8080/chat \
  -H "Content-Type: application/json" \
  -d '{"text": "What is the capital of France?"}'

curl -X POST http://localhost:8080/reason \
  -H "Content-Type: application/json" \
  -d '{"observation": "If A > B, what follows?"}'

11. Cognitive Context (`CognitiveContext`)

The CognitiveContext object is the universal result container returned by chat(). It holds the output of every cognitive stage.

ctx = xyberos.chat("Hello")

# Each stage populates a section of the context
ctx.observation   # Raw input + parsed + normalized + entities + keywords
ctx.thought       # Reasoning result (summary, confidence, trace)
ctx.goal          # Identified goal (description, priority, status)
ctx.plan          # Generated plan (steps, status)
ctx.decision      # Selected decision (choice, confidence)
ctx.action        # Executed action (name, result, metadata)

# Safe access (fields may be None)
if ctx.thought:
    print(f"Thought: {ctx.thought.summary} (confidence: {ctx.thought.confidence})")
if ctx.action:
    print(f"Action: {ctx.action.name} → {ctx.action.result}")

12. Entry-Point Discovery (for third-party packages)

Third-party packages can register tools, skills, agents, and knowledge providers via pyproject.toml entry points:

[project.entry-points."xyberos.tools"]
my_tool = "my_package:MyTool"

[project.entry-points."xyberos.skills"]
my_skill = "my_package:MySkill"

[project.entry-points."xyberos.agents"]
my_agent = "my_package:MyAgent"

[project.entry-points."xyberos.processors"]
my_processor = "my_package:MyProcessor"

[project.entry-points."xyberos.providers"]
my_provider = "my_package:MyProvider"

Summary

Layer	Import Path	Key Class(es)
Façade	`xyberos`	`XYBEROS` (singleton: `xyberos`)
Functional	`xyberos.api`	`chat()`, `reason()`, `plan()`, etc.
Config	`xyberos.config`	`XyberosConfig`
Tools	`xyberos.tools`	`ToolManager`, `Tool`
Agents	`xyberos.agents`	`AgentManager`, `Agent`, `CollaborationEngine`
Skills	`xyberos.skills`	`SkillManager`, `Skill`
Memory	`xyberos.memory`	`MemoryManager`
Knowledge	`xyberos.knowledge`	`KnowledgeManager`
Brain	`xyberos.brain`	`Brain`, `CognitiveContext`
Server	`xyberos.server`	FastAPI REST endpoints