Build your first Origo Source

Get the builder Skill

Download origo-source-builder and keep the complete extracted folder. Place it in the Skill directory supported by your assistant, or ask the assistant to read SKILL.md directly.

Use $origo-source-builder to create my source for original articles and serial chapters.
Keep IDs stable, support chapter updates, and verify the service with real HTTP requests.

The kit includes scaffolding, a runnable Python starter, canonical schemas, original profile fixtures and validators. For an existing service, ask the assistant to add an adapter while retaining your stack and storage.

Generate and run

Use Python 3.11 or newer. Run from your code workspace and replace /path/to/origo-source-builder with the actual extracted Skill path:

python "/path/to/origo-source-builder/scripts/create_source.py" ./my-source --id org.example.my-library --name "My library"
cd my-source
python server.py --port 8787

Choose your own globally unique source ID before publishing; org.example is only an example. The generator refuses to overwrite an existing directory. The starter needs only Python's standard library; it implements core text reading, browsing and chapter updates, listening on loopback.

Its discovery URL is:

http://127.0.0.1:8787/.well-known/origo-source.json

Add your content

Edit library.json with your books and chapters. Retain published IDs when correcting content. New chapters get new IDs; title/order changes also invalidate the catalog snapshot.

{
  "id": "org.example.my-library",
  "name": "My library",
  "books": [{
    "id": "my-first-book",
    "title": "A page for tomorrow",
    "chapters": [{
      "id": "chapter-1",
      "title": "First chapter",
      "order": 0,
      "content": "Your own writing belongs here."
    }]
  }]
}

The service reloads cached snapshots when the file changes. Write to a temporary file and atomically replace the library to avoid partially written input. Storage lives in library.py; HTTP lives in server.py. A future database adapter can retain the endpoints. The file adapter has an 8 MiB limit; larger libraries should use indexed storage and separate chapter bodies.

Check the actual service

Keep the server running and open another terminal in the generated project:

python -m pip install -r contract/requirements.txt
python contract/scripts/probe_source.py http://127.0.0.1:8787/.well-known/origo-source.json --allow-loopback

The tool sends GET requests and does not retain chapter bodies. It samples one book/chapter; also verify your requested profiles. Correct text without increasing count, check updates and use an old catalog version to confirm 409.

Bundled reference suites validate contract fixtures, not your service. Adding EPUB, images, audio or rankings requires real endpoint/asset checks before capability advertisement.

Publish your own endpoint

For an authorized server deployment, put the service behind an HTTPS reverse proxy and configure the public origin:

python server.py --port 8787 --public-origin https://books.example.org

Discovery must advertise the public apiBaseUrl rather than loopback. Store and back up content outside immutable code releases. The starter provides reading endpoints; author publishing and login need separate implementations.

Read profiles and updates. Exact package provenance is in the download metadata.

Direct HTTPS is also supported. Supply the certificate chain and key together, stored outside your source repository:

python server.py --tls-cert /secure/fullchain.pem --tls-key /secure/private.pem --public-origin https://books.example.org