Writing docs with an agent (Python SDK)

Walk-through: a Python script (or an agent that can write Python) drafting docs by talking to ScaiCMS through the official SDK.

Install#

bash
pip install -e sdks/python-docs   # monorepo dev
# or, once published:
# pip install scaicms-docs

Connect#

python
import os
from scaicms_docs import DocsClient

c = DocsClient(
    base_url=os.environ["SCAICMS_DOCS_URL"],
    api_key=os.environ["SCAICMS_DOCS_API_KEY"],
)

Set those env vars from the API key your admin issued (see Connecting an agent).

Discover the tree#

python
for ns in c.namespaces.list():
    print(ns.slug, ns.visibility)

tree = c.pages.tree("scaicms", "v1")
def show(nodes, depth=0):
    for n in nodes:
        print("  " * depth + n.path + "  — " + n.title)
        show(n.children, depth + 1)
show(tree)

Read a page (raw markdown)#

python
md = c.pages.read_raw("scaicms", "v1", "concepts/architecture")
# Now feed `md` to your LLM for transformation, summarisation, etc.

Write a page#

python
saved = c.pages.upsert(
    "scaicms", "v1", "concepts/your-new-page",
    title="Your new page",
    body_md=open("draft.md").read(),
    frontmatter={"audience": "developers", "summary": "Drafted by my agent."},
    comment="Drafted by my agent at 2026-05-16",
)
print(saved.current_revision)

Each upsert is a revision. You can read the page back, mutate it, write it again — current_revision increments each time.

Search#

python
result = c.search.query("how do I shard models", namespace="scaigrid", limit=5)
for hit in result.hits:
    print(hit.path, "→", hit.anchor, hit.snippet[:80])

Error handling#

python
from scaicms_docs import PermissionDenied, ValidationFailed

try:
    c.pages.upsert("locked", "v1", "x", title="Y", body_md="...")
except PermissionDenied as e:
    print("scope blocks this write:", e.message)
except ValidationFailed as e:
    print("payload rejected:", e.message)

CLI#

For one-off shell automation:

bash
scaicms-docs read scaicms/v1/concepts/architecture
echo "# New page" | scaicms-docs write scaicms/v1/concepts/new --title "New"
scaicms-docs search "weaviate"

The agent bundle at docs/agent-bundle/ packages this guide together with the OpenAPI spec and MCP tool schema, ready to feed to an LLM.