M004 — Developer Platform

Project: XYBEROS AI Platform
Milestone: M004
Status: 🚧 In Progress
Version: v0.6.0
Planned Release: v0.7.0

Executive Summary

M004 shifts focus from engine capabilities to developer experience and production readiness. After three milestones building the kernel (M001), runtime (M002), and cognitive brain (M003), XYBEROS has a powerful internal architecture — but the surface area for developers, integrators, and operators needs hardening.

This milestone delivers: - A hardened REST API with authentication, middleware, and streaming - A typed Python SDK for local and remote usage - Stable, documented public imports - Production-grade observability (structured logging, OpenTelemetry, Prometheus) - CI/CD pipelines for docs, Docker images, and releases - Developer tooling (CLI, auto-completion, --version) - Secrets management (Vault integration) - Multi-tenant security - New LLM backends (Vertex AI, Bedrock, Azure OpenAI, vLLM)

Scope

Area	What's being delivered	Status
M004a — REST API Hardening	Auth middleware, streaming SSE/WebSocket, API versioning, rate limiting, error standardization	✅ Completed
M004b — Python SDK	Typed `XyberosClient` for local and remote, async support, connection pooling	🚧 Planned
M004c — Stable Public API	Clean `from xyberos import ...` surface, deprecation cleanup, `__init__.py` convention fix	🚧 Planned
M004d — Authentication & Security	JWT/OAuth2 integration, API key auth, scoped access control for endpoints	✅ Completed
M004e — Production Observability	Structured JSON logging, OpenTelemetry spans on all kernel operations, graceful shutdown	🚧 Planned
M004f — CI/CD & Infrastructure	Docs build in CI, Docker image push to GHCR, release automation, version checks	🚧 Planned
M004g — Developer Tooling	`--version` CLI flag, auto-completion, async CLI, runtime introspection CLI commands	🚧 Planned
M004h — Documentation Overhaul	Fix MkDocs nav, API reference, SDK reference, migration guide, example gallery	🚧 Planned
M004i — Secrets Manager	Vault/Bitwarden integration, env fallback, TTL caching	✅ Completed
M004j — Multi-Tenant Security	Tenant isolation in Principal/SecurityContext, storage/database wrappers	✅ Completed
M004k — New LLM Backends	Google Vertex AI, AWS Bedrock, Azure OpenAI, vLLM	✅ Completed
M004l — Plugin Marketplace	Registry listing, publishing guide, docs	✅ Completed

Current Status (baseline)

Metric	Value
Python LOC	~30,388
Python files	580
Test files	45
Tests passing	1,729
Entry point groups	12
Registered plugins	54
Kernel services	14
Brain subsystems	14
Memory tiers	6
LLM backends	5
Reasoning strategies	7
REST API endpoints	7 (chat, reason, plan, memory, action, tools, health)
Docker support	Dockerfile + docker-compose.yml (no CI push)
Documentation	MkDocs site (nav partially broken)

M004a — REST API Hardening

The FastAPI server (xyberos/server/app.py) exists with functional routes but lacks production features.

Already implemented

✅ Chat, Reason, Plan, Memory, Action, Tools endpoints
✅ Health check (/health) with dependency status
✅ Prometheus metrics (/metrics)
✅ Runtime introspection (/system/status, /system/info)
✅ Request timing middleware
✅ Global exception handler
✅ OpenAPI docs (/docs, /redoc)

To be delivered

Feature	Detail
Streaming responses	SSE (`text/event-stream`) for real-time agent output on chat and reason endpoints
WebSocket support	Bidirectional streaming for interactive agent sessions
API versioning	`/v1/chat`, `/v1/reason` — backwards-compatible evolution
Rate limiting	Per-client rate limits with configurable quotas
Standardized error responses	Consistent RFC 7807 Problem Details for all error responses
Request validation	Pydantic models with detailed validation error messages
CORS middleware	Configurable CORS for web clients
OpenAPI improvements	Operation IDs, summary/description on all endpoints, response models

M004b — Python SDK

A typed, importable client that works identically whether connecting to a local xyberos instance or a remote server.

xyberos/
  client/                  # New package
    __init__.py
    client.py              # XyberosClient (local mode)
    remote_client.py       # RemoteXyberosClient (HTTP mode)
    models.py              # Request/response types
    errors.py              # Typed exceptions
    transport.py           # HTTP transport with retry + pooling

Key design

from xyberos.client import XyberosClient

# Local mode — uses internal runtime directly
client = XyberosClient()
ctx = client.chat("Hello")

# Remote mode — connects to XYBEROS REST API
remote = XyberosClient(remote="https://xyberos.example.com", api_key="...")
ctx = remote.chat("Hello")

Features

Same interface for local and remote — swap via remote= parameter
Async variants (achat, areason, aplan)
Connection pooling and automatic retry
Typed request/response models
Token-aware streaming callbacks
Automatic endpoint discovery from server

M004c — Stable Public API

Public import surface

The goal is a clean, intuitive from xyberos import ... experience:

from xyberos import xyberos          # Singleton facade
from xyberos.client import XyberosClient  # SDK client
from xyberos.config import XyberosConfig  # Configuration
from xyberos.tools import Tool       # Tool base class
from xyberos.agents import Agent     # Agent base class
from xyberos.skills import Skill     # Skill base class
from xyberos.plugins import Plugin   # Plugin base class
from xyberos.memory import Memory    # Memory facade
from xyberos.brain import Brain      # Cognitive brain
from xyberos.security import SecurityContext

Cleanup tasks

Task	Detail
Fix `__init__.py` convention	Move class implementations out of `__init__.py` into named files (e.g., `engine.py`, `manager.py`). Keep `__init__.py` as re-export only — matches how `tools/`, `agents/`, `skills/` are structured
Remove deprecated modules	Remove `skills.discovery` and `agents.discovery` (deprecated since v0.4.0)
Audit exports	Ensure every `__all__` is accurate and nothing internal is accidentally exported
Add deprecation warnings	Any remaining v0.4.x APIs get `DeprecationWarning` with migration hints

M004d — Authentication & Security

API Authentication

Feature	Detail
API key auth	`X-API-Key` header authentication for server endpoints
JWT tokens	Bearer token with configurable expiry, refresh flow
OAuth2 integration	Optional OAuth2 flow for web dashboards
Scoped access	Endpoint-level permission scopes (read:memory, write:memory, execute:action)

Middleware pipeline

Request → API Key Check → JWT Verification → Scope Check → Rate Limit → Handler

All integrated with the existing Guardian Engine for policy evaluation.

M004e — Production Observability

Already implemented

✅ TelemetryService — OpenTelemetry tracer provider
✅ MetricsService — Prometheus metrics with request/error recording
✅ Health check endpoint
✅ Runtime introspection endpoints
✅ observability extras in pyproject.toml

To be delivered

Feature	Detail
Structured logging	Replace `logging.info(...)` with JSON-structured logs (loguru or structlog)
OTel spans on kernel operations	Automatic spans for every kernel service call with duration, status, metadata
OTel spans on brain pipeline	Per-stage spans for perceive → reason → plan → decide → act → reflect → remember
Graceful shutdown	Wire Kill Switch into SIGTERM/SIGINT handlers for clean teardown
Async CLI	Make CLI fully async so it doesn't block during agent reasoning
Log level configuration	Environment-variable-driven log level (default: INFO, debug: DEBUG)
Audit log export	Structured audit events streamed to stdout/file in JSON format

M004f — CI/CD & Infrastructure

Already implemented

✅ GitHub Actions publish workflow with trusted publishing
✅ Dockerfile (multi-stage build)
✅ docker-compose.yml
✅ Makefile with common tasks

To be delivered

Pipeline	Detail
Docs CI/CD	`mkdocs build --strict` runs on every PR; deploy to GitHub Pages on release tags
Docker image push	Push to GHCR on every release tag; also push `:latest` on default branch
Release automation	Auto-create GitHub Release with changelog when version tag is pushed
Pre-commit hooks	`.pre-commit-config.yaml` with ruff, mypy, trailing-whitespace checks
Code coverage reporting	Upload coverage to Codecov or similar on CI runs
Dependency vulnerability scan	`pip-audit` or Dependabot for dependency CVE detection

M004g — Developer Tooling

CLI improvements

Feature	Detail
`xyberos --version`	Print package version and exit
`xyberos --info`	Print system info (Python version, entry points, plugins loaded)
`xyberos status`	Show runtime status (active agents, memory usage, uptime)
Shell completion	`xyberos --completion bash` / `zsh` / `fish`
Async CLI	Convert CLI to async so commands don't block during agent reasoning

M004h — Documentation Overhaul

Already implemented

✅ MkDocs site with Material theme
✅ Getting Started guide
✅ Multi-page docs (agents, skills, memory, knowledge, tools, plugins, config)
✅ API-SDK reference page
✅ Migration guide
✅ Milestone documents (M001–M003)
✅ Examples directory (chatbot, multi-agent, rag, research-agent, workflow)

To be delivered

Task	Detail
Fix MkDocs nav	✅ Done — nav now includes Security docs, Plugin Marketplace, and M004 milestone
Add M004 to nav	Add `M004 — Developer Platform: milestone/M004-Developer-Platform.md` to mkdocs.yml
Security documentation	Document Guardian Engine, Risk Engine, Audit, policy model for developers
API reference page	Proper OpenAPI-derived reference, not manually maintained
SDK reference	Document `XyberosClient` API with examples
Example gallery	One-page overview of all examples with short descriptions and links
Architecture diagram	Mermaid diagram showing Kernel → Runtime → Brain → API → Client layers
Quick-start video/gif	Terminal recording of `pip install xyberos` → `xyberos.chat("hello")`

M004i — Secrets Manager

A pluggable secrets management subsystem (xyberos/security/secrets/) that eliminates hard-coded credentials.

Implemented

Component	File	Purpose
SecretsProvider (ABC)	`xyberos/security/secrets/providers.py`	Abstract interface for secrets backends
EnvSecretsProvider	`xyberos/security/secrets/providers.py`	Reads from environment variables (zero-config default)
VaultSecretsProvider	`xyberos/security/secrets/providers.py`	HashiCorp Vault via `hvac`, auto-fallback to env
SecretsManager	`xyberos/security/secrets/manager.py`	Orchestrator with TTL-based caching
Config integration	`XyberosConfig`	`secrets_provider`, `vault_addr`, `vault_token`, `vault_mount_point`, `secrets_cache_ttl`
Env var mappings	`config/loaders/env.py`	`XYBEROS_SECRETS_PROVIDER`, `XYBEROS_VAULT_*`

Usage

from xyberos.security.secrets import SecretsManager, VaultSecretsProvider

mgr = SecretsManager(
    provider=VaultSecretsProvider(),
    cache_ttl=300,  # 5-minute cache
)
api_key = mgr.get("OPENAI_API_KEY")  # Falls back to env var

M004j — Multi-Tenant Security

Tenant isolation across the entire platform — from principal identity through storage and database backends.

Implemented

Component	File	Purpose
Tenant model	`xyberos/security/models.py`	`Tenant(id, name, settings)` dataclass
Principal.tenant_id	`xyberos/security/models.py`	Scopes principal to an organization
SecurityContext.tenant_id	`xyberos/security/models.py`	Derived from principal or request metadata
resolve_tenant_id()	`xyberos/security/models.py`	Falls back to `XYBEROS_DEFAULT_TENANT` env var
TenantStorageWrapper	`xyberos/storage/tenant.py`	Prefixes storage keys with `{tenant_id}:`
TenantDatabaseWrapper	`xyberos/database/tenant.py`	Supports `column` and `table_prefix` isolation

Storage isolation

from xyberos.storage.tenant import TenantStorageWrapper
from xyberos.storage.memory import InMemoryStorageProvider

tenant_a = TenantStorageWrapper(InMemoryStorageProvider(), tenant_id="acme")
tenant_b = TenantStorageWrapper(InMemoryStorageProvider(), tenant_id="beta")

tenant_a.save("key", "secret-data")   # stored as "acme:key"
tenant_b.save("key", "other-data")    # stored as "beta:key"
# Cross-tenant leakage is impossible — keys are prefixed

M004k — New LLM Backends

Four additional LLM backends have been added to the existing five, bringing the total to 9 backends.

Added backends

Backend	Env vars	Package
Google Vertex AI	`GOOGLE_CLOUD_PROJECT`, `VERTEX_AI_LOCATION`, `VERTEX_AI_MODEL`	`google-generativeai`
AWS Bedrock	`AWS_REGION`, `BEDROCK_MODEL`	`boto3`
Azure OpenAI	`AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_KEY`, `AZURE_OPENAI_DEPLOYMENT`	`openai`
vLLM	`VLLM_BASE_URL`, `VLLM_MODEL`, `VLLM_API_KEY`	`openai`

Full registry

_BACKEND_REGISTRY = {
    "openai": OpenAIBackend,
    "anthropic": AnthropicBackend,
    "ollama": OllamaBackend,
    "openai_compatible": OpenAICompatibleBackend,
    "simulated": SimulatedBackend,
    "vertex_ai": GoogleVertexAIBackend,      # New
    "bedrock": AWSBedrockBackend,             # New
    "azure_openai": AzureOpenAIBackend,       # New
    "vllm": VLLMBackend,                      # New
}

M004l — Plugin Marketplace

A community plugin registry with publishing guidelines and documentation.

Implemented

Feature	Detail
Plugin marketplace page	`docs/plugin-marketplace.md` — listing, how-to, requirements
MkDocs nav entry	Added to mkdocs.yml navigation
Publishing guide	Step-by-step: implement Plugin ABC → register entry points → package → submit
Entry-point groups documented	All 12 groups with counts of built-in plugins
Roadmap	CLI install, remote registry, sandboxing, signing

Architecture (M004 Target)

graph TB
    subgraph "External"
        CLI[xyberos CLI]
        SDK[XyberosClient SDK]
        HTTP[REST / HTTP]
        WS[WebSocket Clients]
    end

    subgraph "API Layer (new in M004)"
        AUTH[Auth Middleware]
        RATE[Rate Limiter]
        VER[API Versioning]
        SSE[SSE Streaming]
    end

    subgraph "XYBEROS Platform"
        FACADE[xyberos Singleton]
        BRAIN[Cognitive Brain]
        RUNTIME[Runtime]
        KERNEL[Kernel]
    end

    subgraph "Observability"
        OTLP[OpenTelemetry]
        PROM[Prometheus]
        LOG[Structured Logging]
    end

    CLI --> FACADE
    SDK --> FACADE
    SDK --> HTTP
    HTTP --> AUTH
    WS --> AUTH
    AUTH --> RATE
    RATE --> VER
    VER --> FACADE
    VER --> SSE

    FACADE --> BRAIN
    BRAIN --> RUNTIME
    RUNTIME --> KERNEL

    KERNEL --> OTLP
    KERNEL --> PROM
    KERNEL --> LOG

Dependency Graph

M004h (Docs) ─────────────────────────────┐
                                          ▼
M004c (Stable API) ───► M004b (SDK) ───► M004a (API Hardening)
       │                                        │
       ▼                                        ▼
M004d (Auth) ───────────────────────────► M004a (needs auth middleware)
       │
       ▼
M004e (Observability) ─── can proceed in parallel
       │
       ▼
M004f (CI/CD) ─── can proceed in parallel
       │
       ▼
M004g (Tooling) ─── can proceed in parallel

M004a, M004b, M004c, and M004d are tightly coupled — do them in order. M004e, M004f, M004g, and M004h can proceed in parallel once the API surface is stable.

Success Criteria

Criteria	Measurement
All REST endpoints have auth, rate limiting, and streaming	Integration tests pass
Python SDK works identically in local and remote mode	SDK integration tests pass
Public API surface is stable and documented	`from xyberos import ...` works as documented
Documentation nav builds without warnings	`mkdocs build --strict` passes
Docker image is published to GHCR	`docker pull ghcr.io/xyberos/xyberos:latest` works
CLI supports `--version`, `--info`, shell completion	CLI smoke tests pass
Structured logging is active in production mode	Log output is valid JSON
Graceful shutdown handles SIGTERM within 5 seconds	Integration test with timeout
All 1,729+ existing tests continue to pass	`pytest tests/ -q` shows no failures

Timeline

Phase	Milestone	Estimated effort	Status
M004d — Auth middleware	v0.6.0	1 week	✅ Completed
M004a — API hardening (versioning, SSE, WebSocket)	v0.6.0	2 weeks	✅ Completed
M004i — Secrets Manager	v0.6.0	1 week	✅ Completed
M004j — Multi-Tenant Security	v0.6.0	1 week	✅ Completed
M004k — New LLM Backends	v0.6.0	1 week	✅ Completed
M004l — Plugin Marketplace	v0.6.0	0.5 week	✅ Completed
M004c — Stable API cleanup	v0.6.1	1 week	🚧 Planned
M004b — Python SDK	v0.6.2	1 week	🚧 Planned
M004e — Observability	v0.6.3	1 week	🚧 Planned
M004f — CI/CD	v0.6.4	1 week	🚧 Planned
M004g — Tooling	v0.6.5	0.5 week	🚧 Planned
M004h — Docs overhaul	v0.6.6	1 week	🚧 Planned
M004 Release	v0.7.0	~8.5 weeks	🚧

Relationship to Prior Milestones

M001 ──► M002 ──► M003 ────► M004
Kernel     Runtime    Brain      Developer Platform
(v0.1.0)   (v0.2.0)  (v0.3.0)   (v0.7.0)
                                 │
                                 ├── REST API hardening
                                 ├── Auth middleware (JWT/API key)
                                 ├── API versioning (/v1/)
                                 ├── SSE + WebSocket streaming
                                 ├── Secrets Manager (Vault)
                                 ├── Multi-tenant security
                                 ├── New LLM backends (9 total)
                                 ├── Plugin marketplace
                                 ├── Python SDK
                                 ├── Observability
                                 ├── CI/CD pipeline
                                 ├── Developer tooling
                                 └── Documentation

M004 wraps the existing engine in a production-grade developer experience. The cognitive pipeline, memory, knowledge, and learning systems are already complete from M003. M004 is the bridge from "working engine" to "adoptable platform".