io.github.Axius-SDC/sdcmodeler

sdcmodeler

The modeler's client for SDCStudio. Search the public catalog, estimate, assemble and publish an SDC4 data model, generate its package and an application. A Python client with httpx as its only dependency, a CLI, and sdcmodeler mcp, an MCP server for any agent.

Why

An agent that builds a feature decides a data model at that moment. With sdcmodeler the data is modeled in SDC by default: the agent searches the catalog first, reuses published components wherever one fits, mints only what is new, publishes the model, and takes the package. The result is interoperable because it is composed from shared, published components, and verifiable because every record validates against a published schema.

The name follows the role pattern of the other Semantic Data Charter servers: sdcvalidator validates, sdcgovernance governs, sdcreader reads, sdcmodeler models. It also names what SDCStudio calls every user: a Modeler.

Install

pip install sdcmodeler

The catalog and estimates need no account. Building needs an SDCStudio API key, created in Settings, API Keys, with the scopes and spending limit the holder should have:

export SDCSTUDIO_API_KEY=sdcs_...

The three layers

The client

from sdcmodeler import SDCStudioClient

c = SDCStudioClient()                       # key from $SDCSTUDIO_API_KEY, URL from $SDCSTUDIO_URL
hits = c.search_components("blood pressure", type="xdquantity")
tree = {
    "label": "Vitals",
    "components": [
        {"ct_id": hits["results"][0]["ct_id"]},            # reuse: free
        {"label": "Pulse", "data_type": "XdCount"},        # mint: 100 credits
    ],
    "clusters": [],
}
estimate = c.estimate(tree, "Vitals")       # the server's estimate: reuse, mint, problems, total_credits, wallet, key, estimate_id
result = c.assemble("Vitals", tree, estimate_id=estimate["estimate_id"])   # 500 credits plus the mints

Every leaf existing: the server assembles, publishes and generates the package in one call (result["mode"] == "reuse"; published and generated say so). Some leaves new: the pipeline runs and result["job_ct_id"] is polled with c.job_status(...), or c.wait_for_job(...), until completed, when the job has published and generated as asked and its result carries the model's links. publish=False leaves a draft for a person to review. The server refuses a build whose tree changed since the estimate.

A 402 is InsufficientCredits with the numbers in credits. A 403 from the key's policy (no spend scope, or past its limit) is KeyPolicyRefused. The client never funds a wallet; a person does that at the wallet page.

The CLI

sdcmodeler search "blood pressure" --type xdquantity
sdcmodeler models "patient"
sdcmodeler model <ct_id>
sdcmodeler artifact <ct_id> xsd --dir ./schemas
sdcmodeler estimate tree.json --title "Vitals"
sdcmodeler build tree.json --title "Vitals" --wait
sdcmodeler job <job_ct_id>
sdcmodeler package <ct_id> --dir ./packages
sdcmodeler app <ct_id> --profile lightweight --dir ./apps
sdcmodeler wallet

The MCP server

sdcmodeler mcp

A JSON-RPC 2.0 stdio server, no SDK, the way sdcvalidator and sdcgovernance are built. A client configuration needs only:

{"command": "uvx", "args": ["sdcmodeler", "mcp"], "env": {"SDCSTUDIO_API_KEY": "sdcs_..."}}

Tool	Does	Spends
search_components	the public catalog by label, type and project	no
list_models, get_model	published models and their artifact routes	no
estimate_model	what a tree would reuse, mint and cost; returns estimate_id	no
build_model	assemble, publish and generate (or publish: false for a draft); needs the estimate_id the person saw; refuses past the key's limit	yes
job_status	one job by id: status, step, cost so far, the model's links	no
download_package	a model's package ZIP with the key, including a model in a private project; builds a missing package first (free, once) unless generate is false	no
generate_app	generate and download the application; needs confirm_charge; 1,500 credits the first time, free after	yes
wallet	balance in credits and the key's policy	no

The policy lives in the server. No spend without an estimate shown: build_model takes the estimate_id that estimate_model returned for the same title and tree in this process. Stop at the key's limit: a build whose estimate exceeds what the key may still spend is refused before the server is asked. Never pay: a 402 is reported with the wallet page's address and the tool stops. No tool takes a URL, a key or a payment method as an argument; the key is the environment the server starts with.

The package or the application

get_model names the artifacts: the XSD 1.1 schema, the instance template, JSON, JSON-LD, SHACL, HTML, GraphQL. The package is a contract with no runtime attached; a feature inside an existing application implements on it, in any language, validating every record locally with sdcvalidator. The generated application (lightweight or enterprise profile) is a Django implementation on the same package, right when the feature is a new service. CordovaOS is ten of them sharing data with zero integration code.

What is not here

Validation (sdcvalidator's server), governance (sdcgovernance's), receipt verification (sdcreceipt's) and bringing existing data across (sdc-agents) are their own registered servers. sdcmodeler composes with them; it does not re-implement them.

Release

Two steps: merge to main, then push the tag v<version> matching pyproject.toml. release.yml runs the tests, builds, publishes to PyPI by trusted publisher and to the MCP registry.

License

Apache License 2.0. Copyright Axius SDC, Inc.