glyphh-ada

Ada for Python. An agent builds an Ada model: its types, its records, its rules. This package is what your software calls to use it. Every answer is typed, the same input always gives the same answer, and no language model is in the path.

Docs: docs.glyphh.ai/ada. No dependencies on Python 3.11 and later. Python 3.9 or later.

pip install glyphh-ada

Ask a model

from glyphh_ada import Ada

ada = Ada()  # GLYPHH_API_KEY from the environment
tickets = ada.model("am_0123456789ab")

answer = tickets.query({"ticket": {"issue": {"component": "kubelet", "symptom": "crash_on_boot"}}})

if answer["act"]:
    route(answer["top"])
elif answer["reason"] == "unseen":
    ask_someone(answer["unseen"])  # ["ticket.issue.component=etcd"]

act is the one thing to branch on. When it is false, reason says why, and the nearest answer and the records behind it are still there. When Ada acts covers every case.

An answer is the JSON the server sent, as a dictionary. The package's TypedDicts (Answer, Facts, History, Trend, Prediction, Edges, GqlResult) say what is in each, so a type checker knows the keys.

Record what happened

tickets.record({"ticket": {"issue": {"component": "kubelet", "symptom": "crash_on_boot", "severity": 7}}}, "route_to_platform")
tickets.veto(situation, "route_to_network")  # this outcome failed here
tickets.record(situation, "route_to_platform", at="2026-01-03T10:00:00Z")  # when it happened, for past records
tickets.load([{"situation": h.situation, "outcome": h.outcome, "at": h.when} for h in history])  # the seed, all or none
tickets.stream(read_records("tickets.ndjson"))  # a file, streamed; a refusal names the line and says how many landed (error.loaded)

Create a typed model

model = ada.create_model("tickets", spec={
    "name": "tickets",
    "layers": [{"name": "ticket", "segments": [{"name": "issue", "roles": [
        {"name": "component", "type": "category"},
        {"name": "severity", "type": "number", "numeric_config": {"min_value": 0, "max_value": 10, "bin_width": 1}},
    ]}]}],
})
print(model.id)

Data that does not fit a role's type is refused before it is stored or scored.

Everything a model does

On the client: ada.models(), ada.create_model(...), ada.contract(), and ada.op(name, **args) for any operation by name.

GQL and the graph

near = tickets.gql("FIND SIMILAR TO $like WHERE outcome = $outcome LIMIT 5", {"like": situation, "outcome": "won"})
for match in near["matches"]:
    print(match["key"], match["score"])

impact = services.gql('FOLLOW glyph("db") IN DEPTH 3')  # everything that depends on db

Worked examples

Two programs that go from an empty model to a function your software calls, each with a step-by-step guide: route support tickets (Python) and customer churn (TypeScript). The source is in examples/.

Errors

A refusal is an AdaError with a code, a message, the HTTP status, and retry_after when Ada says how long to wait.

from glyphh_ada import AdaError

try:
    tickets.query({"ticket": {"issue": {"severity": "high"}}})
except AdaError as e:
    if e.code == "E_VALIDATION":
        print(e.message)  # situation: ticket.issue.severity: a numeric role takes a finite number

Options

Ada(api_key=None, base_url=None, timeout=30.0, headers=None, transport=None)

api_key defaults to GLYPHH_API_KEY, base_url to GLYPHH_URL and then https://api.glyphh.ai. transport is a function (url, headers, body, timeout) -> (status, body) or (status, body, response headers): give your own to use another HTTP library. The client is synchronous; call it from a thread in async code. Create a key on the Virtual Keys page of the Glyphh console. Every call is metered on your organization's plan.

License

MIT