xml-pipeline/docs/configuration.md

Configuration — organism.yaml

The entire organism is declared in a single YAML file (default: config/organism.yaml).
All listeners, agents, and federation gateways are instantiated from this file at startup.
Changes require a restart (hot-reload planned for future).

Example Full Configuration

organism:
  name: "ResearchSwarm-01"
  identity: "config/identity/private.ed25519"   # Ed25519 private key for signing
  port: 8765
  tls:
    cert: "certs/fullchain.pem"
    key: "certs/privkey.pem"

meta:
  enabled: true
  allow_list_capabilities: true      # Public catalog of capability names
  allow_schema_requests: "admin"     # "admin" | "authenticated" | "none"
  allow_example_requests: "admin"
  allow_prompt_requests: "admin"
  allow_remote: false                # Federation peers can query meta

listeners:
  - name: calculator.add
    payload_class: examples.calculator.AddPayload
    handler: examples.calculator.add_handler
    description: "Integer addition"

  - name: calculator.subtract
    payload_class: examples.calculator.SubtractPayload
    handler: examples.calculator.subtract_handler

  - name: summarizer
    payload_class: agents.summarizer.SummarizePayload
    handler: agents.summarizer.summarize_handler
    description: "Text summarization via local LLM"

agents:
  - name: researcher
    system_prompt: "prompts/researcher_system.txt"
    tools:
      - calculator.add
      - calculator.subtract
      - summarizer
      - name: web_search                # Remote tool via gateway below
        remote: true

gateways:
  - name: web_search
    remote_url: "wss://trusted-search-node.example.org"
    trusted_identity: "pubkeys/search_node.ed25519.pub"
    description: "Federated web search capability"

Sections Explained

organism

Core server settings.

• name: Human-readable identifier (used in logs, discovery).
• identity: Path to Ed25519 private key (for envelope signing, federation auth).
• port / tls: Single-port WSS configuration.

meta

Controls the privileged introspection facility (https://xml-platform.org/meta/v1).

• allow_list_capabilities: Publicly visible catalog (safe).
• allow_*_requests: Restrict schema/example/prompt emission to admin or authenticated sessions.
• allow_remote: Whether federation peers can query your meta namespace.

listeners

All bounded capabilities. Each entry triggers autonomous registration:

• name: Logical capability name (used in discovery, YAML tools lists). Dots allowed for hierarchy.
• payload_class: Full import path to the @xmlify dataclass (defines contract).
• handler: Full import path to the handler callable (dict → bytes).
• description: Optional human-readable text (included in list-capabilities).

At startup:

1. Import payload_class and handler.
2. Instantiate Listener(payload_class=..., handler=..., name=...).
3. bus.register(listener) → XSD synthesis, Lark grammar generation, prompt caching.

Filesystem artifacts:

• XSDs cached as schemas/<name_with_underscores>/v1.xsd (dots → underscores for Linux safety).

agents

LLM-based reasoning agents.

• name: Agent identifier.
• system_prompt: Path to static prompt file.
• tools: List of local capability names or remote references.
  • Local: direct name match (calculator.add).
  • Remote: name: + remote: true → routed via matching gateway.

Live capability prompts are auto-injected into the agent's system prompt at runtime (no stale copies).

gateways

Federation peers.

• name: Local alias for the remote organism.
• remote_url: WSS endpoint.
• trusted_identity: Path to remote's Ed25519 public key.
• description: Optional.

Remote tools referenced in agents.tools are routed through the gateway with matching name.

Future Extensions (planned)

• Hot-reload of configuration.
• Per-agent privilege scoping.
• Capability versioning in YAML (version: v2).

This YAML is the single source of truth for organism composition.
Edit → restart → new bounded minds appear, fully self-describing and attack-resistant.