515c738abb
Comprehensive documentation set for XWiki: - Home, Installation, Quick Start guides - Writing Handlers and LLM Router guides - Architecture docs (Overview, Message Pump, Thread Registry, Shared Backend) - Reference docs (Configuration, Handler Contract, CLI) - Hello World tutorial - Why XML rationale - Pandoc conversion scripts (bash + PowerShell) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
159 lines
4.1 KiB
Markdown
159 lines
4.1 KiB
Markdown
# Quick Start
|
|
|
|
Get an organism running in 5 minutes.
|
|
|
|
## 1. Install the Package
|
|
|
|
```bash
|
|
pip install xml-pipeline[console]
|
|
```
|
|
|
|
## 2. Create a Project Directory
|
|
|
|
```bash
|
|
mkdir my-organism
|
|
cd my-organism
|
|
```
|
|
|
|
## 3. Initialize Configuration
|
|
|
|
```bash
|
|
xml-pipeline init my-organism
|
|
```
|
|
|
|
This creates:
|
|
```
|
|
my-organism/
|
|
├── config/
|
|
│ └── organism.yaml
|
|
├── handlers/
|
|
│ └── hello.py
|
|
└── .env.example
|
|
```
|
|
|
|
## 4. Examine the Generated Files
|
|
|
|
### config/organism.yaml
|
|
|
|
```yaml
|
|
organism:
|
|
name: my-organism
|
|
port: 8765
|
|
|
|
listeners:
|
|
- name: greeter
|
|
payload_class: handlers.hello.Greeting
|
|
handler: handlers.hello.handle_greeting
|
|
description: A friendly greeting handler
|
|
peers: []
|
|
```
|
|
|
|
### handlers/hello.py
|
|
|
|
```python
|
|
from dataclasses import dataclass
|
|
from third_party.xmlable import xmlify
|
|
from xml_pipeline.message_bus.message_state import HandlerMetadata, HandlerResponse
|
|
|
|
@xmlify
|
|
@dataclass
|
|
class Greeting:
|
|
"""A greeting request."""
|
|
name: str
|
|
|
|
@xmlify
|
|
@dataclass
|
|
class GreetingResponse:
|
|
"""A greeting response."""
|
|
message: str
|
|
|
|
async def handle_greeting(payload: Greeting, metadata: HandlerMetadata) -> HandlerResponse:
|
|
"""Handle a greeting and respond."""
|
|
return HandlerResponse(
|
|
payload=GreetingResponse(message=f"Hello, {payload.name}!"),
|
|
to=metadata.from_id, # Reply to sender
|
|
)
|
|
```
|
|
|
|
## 5. Run the Organism
|
|
|
|
```bash
|
|
xml-pipeline run config/organism.yaml
|
|
```
|
|
|
|
You should see:
|
|
```
|
|
Organism: my-organism
|
|
Listeners: 1
|
|
Root thread: abc123-...
|
|
Routing: ['greeter.greeting']
|
|
```
|
|
|
|
## 6. Try the Interactive Console
|
|
|
|
If you installed with `[console]`:
|
|
|
|
```bash
|
|
python -m examples.console
|
|
```
|
|
|
|
Type `@greeter Alice` to send a greeting message.
|
|
|
|
## What Just Happened?
|
|
|
|
1. **Payload defined** — `Greeting` dataclass with `@xmlify` decorator
|
|
2. **XSD generated** — Schema auto-created at `schemas/greeter/v1.xsd`
|
|
3. **Handler registered** — `handle_greeting` mapped to `greeter.greeting` root tag
|
|
4. **Message pump started** — Waiting for messages
|
|
|
|
## Understanding the Message Flow
|
|
|
|
```
|
|
Input: @greeter Alice
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────┐
|
|
│ XML Envelope Created │
|
|
│ <message> │
|
|
│ <meta> │
|
|
│ <from>console</from> │
|
|
│ <to>greeter</to> │
|
|
│ <thread>uuid-123</thread> │
|
|
│ </meta> │
|
|
│ <greeting> │
|
|
│ <name>Alice</name> │
|
|
│ </greeting> │
|
|
│ </message> │
|
|
└─────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────┐
|
|
│ Pipeline Processing │
|
|
│ 1. Repair (fix malformed XML) │
|
|
│ 2. C14N (canonicalize) │
|
|
│ 3. Envelope validation │
|
|
│ 4. Payload extraction │
|
|
│ 5. XSD validation │
|
|
│ 6. Deserialization → Greeting │
|
|
│ 7. Route to greeter handler │
|
|
└─────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────┐
|
|
│ Handler Execution │
|
|
│ handle_greeting( │
|
|
│ payload=Greeting(name="Alice"), │
|
|
│ metadata=HandlerMetadata(...) │
|
|
│ ) │
|
|
│ → HandlerResponse(...) │
|
|
└─────────────────────────────────────┘
|
|
│
|
|
▼
|
|
Output: Hello, Alice!
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
- [[Writing Handlers]] — Create your own handlers
|
|
- [[Configuration]] — Customize organism.yaml
|
|
- [[Hello World Tutorial]] — Step-by-step tutorial
|