Python changelog
Release notes for k9o, from the CHANGELOG.md in the sdk-python repository. Read on 17 November 2026 at 15:55 UTC.
1.5.2
Changed
K9O_TIER_FEATURE_GATEDis no longer documented as an error to expect: the platform no longer gates features by plan.- The
tierGatingoption is removed from sign-in provider creation; the platform no longer gates features by plan. - README: Architecture at a glance, illustrations, and the package table lists only the packages for that SDK.
1.5.0
Added
approvals.comments.add(pending_id, body, visibility)andapprovals.comments.list(pending_id, limit=, cursor=)(POSTandGET /@<project>/pending-approvals/<id>/comments): comments on a pending change.bodyis plain text of 1 to 4000 characters;visibilityiseveryoneorapprovers_onlyand is fixed when posted. There is no edit or delete, and a comment never decides the change. Posting needs a session: a personal access token alone is refused (403K9O_RBAC_DENY).listanswers the comments the caller may see, oldest first, 1 to 200 at a time;meta.cursor.nextis the cursor of the next page andNoneon the last. Errors:K9O_APPROVAL_COMMENT_NOT_ELIGIBLE(403),K9O_APPROVAL_COMMENT_CLOSED(409),K9O_INVALID_FIELD_VALUE(400),K9O_NOT_FOUND(404).ApprovalCommenttypes the data.- A page that carries
nextCursorbesidedataand nometa.cursornow reads its cursor frommeta.cursor.next. realtime.replay(topic, from_sequence=, until_sequence=, limit=)(POST /@<project>/realtime/replay): catch up on past events for a topic.topicis required; it answers aRealtimeReplayPage(topic,events,next_cursor,has_more,resync). Topics the gateway keeps no log for answer no events andresyncset to"reread-source".audit.replayis unchanged.schema.collections.get(name)(GET /@<project>/schema/collections/<name>): one collection with its columns, indexes and relationships.KError.request_idis filled from the gateway'sx-k9o-request-idresponse header on every non-2xx answer (requests, raw downloads, stream opens, realtime subscribe and the Rampart key feed) when the error body carries none; arequestIdin the body wins, and without either it staysNone.gate.sign_inasks the project which region holds the email before it sends the password (POST /@<project>/gate/locatewith only the email, noAuthorizationheader). The password goes to the located origin only if it ishttpsand a region host of the same org, gateway family and apex as the base URL, with no userinfo, port, path, query or fragment; anything else, or no origin in the answer, uses the base URL. Nothing is cached except a bounded hint (64) per refresh token sorefresh_tokenandsign_outreach the region that issued the session. A non-2xx answer from the region step (429K9O_RATE_LIMITED, 503K9O_GATE_REGION_UNAVAILABLE) is raised asKErrorbefore the password is sent, with no retry. If the project's locate step answers 404, the client uses the base address.- The Kibo client core matches the configured key against the call's
expected_key_refsbefore it fetches a federated token or exchanges a credential; a key outside the call's pin getsK9O_CRYPTO_UNEXPECTED_KEYon every item, with no token fetch and no seal or open. crypto.mode()andcrypto.mode(crypt)return the gateway'sroute("client"or"server") asCryptoMode.route,Noneon older gateways or for an unknown value; follow it, notcustody_mode.- The custody check before each
encryptnames the crypt (GET /crypto/mode?crypt=<crypt>), so a personal access token or workload policy scoped to named crypts can encrypt;crypto.mode()still sends no query. crypto.mode(crypt=None)takes an optional crypt and sends?crypt=<crypt>; a bad crypt is refused withK9O_INVALID_FIELD_VALUEbefore sending. With none it is unchanged.crypto.encryptfollows theroutefield of the project's custody mode answer (GET /crypto/mode, read fresh before every encrypt). On a BYOK or HYOK project only an explicitroute: "server"sends plaintext to the platform (the answer must also carry a non-emptyepoch); a missingrouteor"client"uses the registered client core. Aroutethat is not"server"or"client"raisesK9O_CRYPTO_CUSTODY_UNKNOWN(contextcustodyMode, androutewhen it is a string) and nothing is sent, in every custody mode.decryptandrewrapare unchanged.crypto.crypts.list(),.create(name)and.retire(name)(GET/POST /crypto/crypts,POST /crypto/crypts/<name>/retire): the project's registered crypt names, returned asCrypt(name,status"active"or"retired",created_at,retired_at). A bad name ([a-z0-9-]{1,64}, notactions) is refused before sending (K9O_INVALID_FIELD_VALUE, fieldname);createsends only{name}andretiresends no body. A malformed gateway answer raisesK9O_INTERNAL_ERROR(crypto.crypts.<op>: the gateway answered ...).createandretireneedcrypto:manage_crypts(project admins by default) and a personal access token is refused onretire. A retired or unregistered name only makesencryptrefuse it;decryptandrewrapnever read the registry. 409K9O_CRYPT_ALREADY_EXISTS, 409K9O_CRYPT_LIMIT_EXCEEDED, 409K9O_CRYPT_RETIREDand 404K9O_CRYPT_NOT_FOUNDarrive asKError, never retried.FederatedTokenhas optionalproviderandproject_id, set only when the gateway sends them as non-empty strings.k9o.kibo.create_kibo_client_core(...): the client core forcryptoon a BYOK or HYOK project, registered withcrypto.use_client_core(core). It fetches a federated token (crypto.federated_token), exchanges it on your own cloud (acquire_kms_credential) and seals or opens on this machine (app_crypto_seal,app_crypto_open) against your own KMS. The key, provider, region, role and endpoint come from your configuration only.expected_key_refsis required and must containkey_ref; a call with an empty pin, a core that does not listexpected_key_refsincore_capabilities()(K9O_CRYPTO_KEY_PIN_UNENFORCED) or one older thanzk-bundle-v2.15.0(KIBO_WASM_ERROR) is refused before any token is fetched. A token naming another provider or project than configured is refused (K9O_INVALID_FIELD_VALUE). The exchange has a deadline (exchange_deadline_secs, default 30;KIBO_EXCHANGE_TIMEOUT); the credential is cached per crypt, operation and subject until 60 s before expiry, and a token is fetched on every call. Item failures are per item with the core's code (UPSTREAM_KMS_ERRORis your own KMS); call-level problems raise. Rewrap is open then seal under the configured key with arewraptoken.crypto.federated_token(crypt, op)(POST /crypto/federated-token): a short-lived identity token (RS256 JWT, at most 15 minutes) to present to your own cloud's token exchange for BYOK and HYOK keys. Returns aFederatedTokenwithtoken,expires_at,issuer,subject,audienceandkid; the token is left out ofrepr. A crypt that does not match[a-z0-9-]{1,64}or isactionsor anopother thanencrypt,decryptorrewrapis refused before sending (K9O_INVALID_FIELD_VALUE). 409K9O_CUSTODY_SERVER_ROUTE, 429K9O_RATE_LIMITEDand 503K9O_KEY_SERVICE_UNAVAILABLEare raised as they come and never retried.cryptonamespace (server-side encryption):crypto.encrypt(crypt, items),decryptandrewrapcallPOST /crypto/encrypt|decrypt|rewrapwith the project key (you never name a key). The SDK base64-encodes plaintext, takes bytes or UTF-8 strings, never parses the opaque ciphertext, and checks the crypt ([a-z0-9-]{1,64}, notactions), 1 to 100 items, 64 KiB per item, 1 MiB per call and a 256-byte context before sending (K9O_INVALID_FIELD_VALUE,K9O_PAYLOAD_TOO_LARGE). Each item has its own result or code; the item shape follows the gateway. Machine calls for service tokens and personal access tokens; extensions, end users and mobile cannot call it; access rules on the crypt decide, default floorPROJECT_EDITOR. The calls route by custody:encryptcheckscrypto.mode()(GET /crypto/mode,{custodyMode, epoch}) on every call with no cache, sends thecustodyEpochwith the request, reroutes once if custody moved (409K9O_ZK_STORE_FLOW_REQUIRED), and never sends plaintext to the platform when the key is in your own KMS or HSM (BYOK or HYOK);decryptandrewraptry the platform first and reroute client-side when the ciphertext belongs to your own key. Register the Kibo client core withcrypto.use_client_core(core)(theClientCoreprotocol) and the same calls work in every custody mode; without one a BYOK or HYOK project gets 501K9O_ZK_CLIENT_CORE_UNAVAILABLE, and an unknown mode or failed mode check fails closed with nothing sent. The ciphertext is covered by the project key's lifecycle only (zeroize or project purge), not by per-subject erasure; client-side Kibo, the extension route and this route do not open each other's ciphertext; decrypt needs the same crypt and context. 400K9O_ENVELOPE_INTEGRITY_FAILUREis one code for every cannot-open, 409K9O_SEALED_UNDER_RETIRED_KEY(rewrapis the fix), 404K9O_CRYPT_NOT_FOUNDand 409K9O_CRYPT_RETIRED(encrypt only; decrypt and rewrap are refused for neither), 413, 429 and 503K9O_KEY_SERVICE_UNAVAILABLEare never retried. The route is not live on the gateway yet.expected_key_refsoption oncreate_client(a non-empty list of key identifiers: ARNs, resource names, key URLs) for projects that use BYOK or HYOK. The crypto router passes it to the registered client core as theexpected_key_refskeyword on everyencrypt,decryptandrewrap, and only when it is set, so a core written without the parameter keeps working while the option is unset. The core refuses a key that is not in the list before it uses any token or makes any network call; the key version is ignored. The list is checked when the client is built (K9O_INVALID_FIELD_VALUE: empty, blank, whitespace or*). A core declares that it enforces the pin withenforces_expected_key_refs = True; with the option set and no declaration the call is refused withK9O_CRYPTO_KEY_PIN_UNENFORCEDbefore the core is called.key_ref_matches(key_ref, expected, provider)is the version-ignoring comparison for core authors;provider("aws", "gcp", "azure" or "vault") is required and never guessed from the reference, and the comparison follows that provider's rule (AWS whole reference; GCP without the version; Azure the first five parts in lower case; Vault<path>/<key>without:<version>). TheClientCoreprotocol documents the new parameter and the declaration.realtime.subscriberesumes by itself: it reconnects withLast-Event-IDafter the server closes a stream (every 300 s) or the connection drops, drops events it already delivered, and treats 45 s without any bytes as a dead connection. Events carryeventId. A 4xx answer raisesKErroronce; 5xx and network errors are retried (delay up to 30 s).on_resyncoption onrealtime.subscribe: called (sync or async) with{"reason", "action"}when the feed position is lost; re-read current state there. The resync frame is not yielded, and the next connection starts withoutLast-Event-ID.metadatanamespace:filter,set,search,vectors.nearest,subscribe, andindex.get/index.declarefor the columns you declare on a collection. Column names inwhere,searchandnearestget themetadata.prefix when you leave it out;setwrites declared columns only.filter,searchandnearestreturn aMetadataPage(datarows,cursor).subscribeuses the same reconnecting reader asrealtime.subscribe(events carry the record id only) and takesfrom_sequence. The SDK checks the surface grammar, limits, cursor rule and the 64-column limit before sending. Gateway codes such asK9O_METADATA_FIELD_NOT_INDEXED,K9O_UNKNOWN_SURFACEandK9O_QUERY_RESULT_TOO_LARGEarrive asKError.rampartnamespace:classify(input, label=)returns the verdict, the signed receipt andproject_id;jwks()reads the public key feed (keysand the deployment'sissuer);verify_receipt(result_or_receipt, input)checks a receipt locally (key bykid,EdDSA,typ, signature, issuer from the key feed or theissuer=option, project from the classify result orproject_id=, time window, and the SHA-256 of the canonicalinputin the platform's JCS code-point profile: keys sorted by UTF-8 byte order, integers only up to 2^53 - 1) and raisesReceiptRefusalwith a closedreasonon any failure (project_unknownwhen a bare receipt has no project id to compare). Rampart is advisory: it never blocks, and an unavailable classifier raisesK9O_RAMPART_CLASSIFIER_UNAVAILABLE. A long input is scored in overlapping windows and the highest injection score decides; past 16 windows (about 6,000 tokens) the answer is 413K9O_RAMPART_INPUT_TOO_LONGwith no verdict, and 503K9O_RAMPART_CLASSIFIER_UNAVAILABLEstill means the classifier could not answer. The thresholds (calibrationrampart-launch-v1) are a starting calibration and may move; a change is a new calibrationVersion. Ed25519 and the canonicalizer are implemented in the package, so there is no new dependency.rampart:verify_receiptreads the receipt'swindowsclaim (the number of windows scored, 1 when the input fit one) intoVerifiedReceipt.windows(Nonewhen the receipt has none) and ignores claims it does not know.classifyraisesRampartInputTooLong(aKError, 413K9O_RAMPART_INPUT_TOO_LONG) past 16 windows; there is never a verdict for it.analyticsnamespace for datasets:list,get,create,delete,query(read-only SQL),read(paged),write,materialize,upload(CSV or JSON file, withdry_runand amanifestthat creates the dataset),download_original, plusanalytics.rollupsandanalytics.schedules(create,list,delete,reattest).rollups.list,rollups.readandrollups.subscriberead and follow rollups;rollups.subscribeuses the same reconnecting reader asrealtime.subscribe. A rollup or schedule pauses when it is not re-attested within itsreattest_interval_days(7, 30, 90 or 365).reattestis for people: a service, workload or extension token gets 403K9O_RBAC_DENY(reasonhuman_only).keysnamespace:list,getandrotatefor the project's encryption keys (metadata only:id,version,status,custodyMode,createdAt,rotatedAt,byokRef,hyokRef). Reading needs the project admin or auditor role; rotating needs the project admin role and a fresh step-up proof, and is limited to 3 rotations in any rolling 24 hours (429K9O_RATE_LIMITED,retry_after_sec).audit.tail(types=)follows the project's audit events live (auditEventId,type,actorType,occurredAt,outcome) with the reconnecting reader ofrealtime.subscribe; on areplay-ledgerresync it catches up throughaudit.replayby itself.audit.replayreads past events after anauditEventIdor from a sequence. The earlier one-shot read isaudit.recent(since_minutes=, limit=);tail(since_minutes=...)still answers it.KError.retry_after_secalso reads a numericRetry-Afterheader when the error body gives none.k9o.moat: a local guard with no network access.Moat(prompt=, input_schema=, output_schema=, filters=)pins the system prompt, refuses role and system markers in untrusted input, enforces input and output schemas (a JSON Schema subset; unknown keywords are rejected at construction) and runs an optional PII filter. Refusals areMoatRefusalwithreasonrole_marker,input_schema,output_schemaorpii.k9o.moat: the role-marker scan matches on text normalised by the Moat contract rule (NFKC, combining marks (Mn, Me) ignored, default-ignorable and format code points removed using a fixed table, a small set of Cyrillic and Greek look-alikes of the marker letters mapped to the Latin letter, case-folded, horizontal whitespace collapsed, line breaks kept) and passes the shared marker vectors.custody.status(): read-only custody status of the project (mode,attached,provider,lastJob,hsm). Needs the project admin or auditor role.KError.retry_after_sec: the number of seconds the gateway asks you to wait, orNone. It is a field only; retry behaviour is unchanged.timeoutoption oncreate_client: a number of seconds (read), a(connect, read)pair or anhttpx.Timeout.timeoutargument onai.generate,ai.embed,compute.llms.invoke,compute.llms.invoke_stream,realtime.subscribeandstreams.subscribe.client.with_options(timeout=...): a client with another timeout, for any method.require_approvalon single-record writes:from_(c).insert(record, require_approval=True), and.require_approval()onupdateanddelete, send?requireApproval=true. The answer is the queued change (HTTP 202) or, when anauto_approvepolicy applies the write, the row:is_queued_write(result)tells them apart.QueuedChangetypes the queued data.approvals.listtakescursor: passmeta.cursor.nextof a page to read the next one (Noneon the last page). An invalid cursor raisesK9O_INVALID_CURSOR.approvals.bulkresults carryfailed, a list of{id, code, reason}for rows that could not be decided (an empty list when none). The call answers HTTP 200 even when rows fail, so compareaffectedIdswith what you intended.BulkApprovalsResultandBulkFailuretype the data.functions.triggers:list,create,updateanddeletefor event triggers on a collection.schedulesnamespace for cron schedules:list,get,create,update,delete,runsandrun_now.end_usersnamespace:listandget, plusend_users.role_grants.list,grantandrevoke.vectorsnamespace:nearest(collection, query_vector, top_k=, min_score=, metric=, filters=)andupsert(collection, rows)for collections of your own embeddings. The vector is sent in the request body (up to 16000 numbers, 1 to 1000 rows per upsert). A collection name must start with_. The SDK checks the name, the vector length and numbers,top_k,metricand the row count before sending.- README: what an event-trigger function receives (the JSON payload, redaction,
triggeredAt, and deduping oneventId).
Fixed
realtime.subscribe,metadata.subscribeandrollups.subscribeno longer reconnect in a loop without delivering anything: on a fresh connection (noLast-Event-IDand nofrom_sequence) the gateway sends oneresyncframe with the current head and then streams events on the same connection. That openingresyncis now informational (on_resyncis not called, the connection is kept); aresyncafter an event was received, or on a connection that sentLast-Event-IDorfrom_sequence, still callson_resyncand restarts withoutLast-Event-ID.audit.tailread the wrong frame: the gateway sends the five fields insidepayload, with the publisher's own SSE id (not theauditEventId) and the audit type as the event name. The tail now yieldsauditEventId,type,actorType,occurredAt,outcomeandeventId, dedupes oneventId, resumes withLast-Event-IDset to the SSEid, and on areplay-ledgerresync replays after the lastauditEventId, pages whilehasMore, and skips events already delivered. After aresyncit now connects fresh first, holds the frames that arrive, replays from the last deliveredauditEventId, then merges replay, held and live events (deduped), so nothing is lost; a repeatedresyncbacks off. A new connection starts at the live head and may re-send the last few seconds of events, each yielded once, and aresyncthat opens a fresh connection is informational (the stream is kept).audit.replaysendslimit: 1000when you give none and refuses a limit outside 1 to 10000 withK9O_INVALID_FIELD_VALUE.audit.replaynow returns anAuditReplayPage(eventsflattened frompayload, withsequenceas a string;next_cursor;has_more) and acceptsafter_audit_event_idtogether withfrom_sequence(the id wins).rollups.subscribeyields the frame'spayloadcell (cellKey,bucket,dims,final,measures) witheventIdandoccurredAt; a cohort-suppressed cell hasstatus,reasonandsuppressedTrue. A resync with actionreread-sourcereacheson_resync.keys.rotate(key_id, step_up=hook)answers a 401K9O_STEP_UP_REQUIREDchallenge (scope_set_root,nonce,methods,max_age_sec,rp_id) with your hook and retries exactly once with thex-k9o-step-up-proofheader; without a hook it raisesStepUpRequiredcarrying the challenge aterror.step_up.keys.listis unpaged:datais{items}and anextCursoris dropped.rampart.classifyrefuses aninputthat is not an object (K9O_INVALID_FIELD_VALUE) before sending.vector_searchon the select builder sends the embedding in the request body (POST data/<collection>/search), so real embeddings no longer fail with HTTP 414. It cannot be combined withtext_search.recommendationonKErroris always text orNone. The gateway may send it as an object ({"action": ...}or{"retryAfterSec": ..., "note": ...}): theactiontext, else thenotetext, is used. Decoding an error no longer depends on the type of this field.- Requests no longer fail after the 5-second httpx default. The defaults are now 10 s to connect and 120 s per read,
so
ai.generate,invoke_streamand idle stream tails work against models that take about 30 s. Stream reads use the read value as an idle timeout, not a total one.
1.4.0 — 2026-10-26
Added
query(sql, params): one read-only SQL statement; a list binds$1, $2, ..., a dict binds:nameplaceholders.search(collection, column=..., q=...): full-text search over one column, plustext_searchandvector_searchonselect().ai.generate: text generation from a prompt (verb sugar overcompute.llms.invoke;modeldefaults to the org's default LLM).streamsnamespace for user data streams:create,list,get,delete,publish,replayandsubscribe.subscribetails live events over SSE and reconnects from the last sequence when the server closes the connection.approvalsnamespace for the pending-change queue:list,get,approve,rejectandbulk.approval_policiesnamespace:list,createanddelete.schema.collections.list: the project's collections with row counts and last migration, paged by cursor.
Changed
- The README description now covers streams and realtime, and the platform overview moved to an "About Kilimanjaro" appendix.
- Function deploy examples use the sandbox tier.
1.3.0 — 2026-10-26
Every method now matches the gateway.
Changed
projects.createtakesdisplay_name(and optionalslug,region,custody_mode, ...);projects.getandprojects.updateuse the projects routes.functions.deploytakesname,runtime,tier(gatewayorsandbox),artifact_key,versionanddescription. Inline code is gone.functions.invokesends the payload as{payload}.policies.create,updateandvalidatetake apolicydocument (plus optionalrules,editor_mode);policies.listtakes onlystatus.audit.queryfilters areevent_type,actor_id,after,before,limitandcursor.- Org roles, identity providers, default model and SMTP changed:
smtp.setusespassword_refandfrom_address;smtp.testtakestoandsubject. me.api_tokens.createtakeslabelandscope_manifest(andttl_seconds);me.sessions.revokeandrevoke_alluse new routes.compute.llms.invokesettings are sent flat, and the result hascontentandusage.studio.workflows.triggersends the context astriggerContext.gate.sign_outrequires the refresh token.kibo.vault.secrets.getlooks a secret up by exact name;regionis optional on every vault method.- The API host comes from the base URL: any
<org>.api.<apex>host works and no apex is hardcoded.https://api.k9o.iois only the default.
Removed
gate.verify_session,gate.hostedandrealtime.replay, and the poll transport ofrealtime.subscribe.me.notifications,me.audit_logandme.data_export.org.groups.create,org.groups.delete,org.members.getandorg.smtp.get.
Added
functions.upload_artifact(data, kind)uploads a build and returns theartifactKeyfordeploy.parse_api_host,ApiHostandDEFAULT_BASE_URLare exported.- A contract test checks every method against the gateway's API description.
1.2.0 — 2026-10-25
- The README now introduces the Kilimanjaro building blocks (Keep, Pulse, Gate, Kibo). No change to the public API.
1.1.1 — 2026-10-25
- Documentation links corrected: the documentation hub is https://docs.kilimanjaro.dev, with the website, platform API and console listed in a Links section. Package metadata points at the same places.
1.1.0 — 2026-10-25
- Documentation rewritten with runnable examples and expected output; internal cross-references removed from the published sources. No change to the public API.
k9o.__version__now reports the installed package version (it previously reported0.3.0).- Fixed: boolean filter values are sent as
true/false.eq("done", False)previously sentFalse. - Error text for
update()/delete()without anidfilter no longer mentions a version or a roadmap.
1.0.0 — 2026-10-23
First public release. See the README for the full API overview.