Import a genome from Python

Status

Not available yet SDK import methods (import_preview, import_consent, import_undo). The methods exist in the SDK, but the routes they call are not mounted on the platform. Each call raises NotFoundError (404).
Needs an IntelliNix workspace with the genome flags on Plain HTTP script against the workspace import routes. Python standard library only. Same flags and administrator rule as the IntelliNix import.
Works today Check the file checksum with hashlib. Needs nothing from IntelliNix.

The SDK import methods do not work yet

client.genome.import_preview, import_consent and import_undo are in the SDK, and the SDK calls them “provisional”. The platform routes behind them are not mounted, so each call raises NotFoundError (404). Use the plain HTTP script below until they are.

Prerequisites

Python 3 with the standard library. The HTTP script needs nothing else.
For the SDK calls: the SDK source names the package intellinix-beta (pip install intellinix-beta) and the module intellinix_sdk. The package index was not checked.
An IntelliNix workspace with agent_genome and genome_format on, and an administrator account, for the import.
Your API address as [YOUR-INTELLINIX-API] and a key as [YOUR-API-KEY].
For reading a genome with the SDK: the genome_public_api flag, and a key with the genome:read scope.

1. Verify the file (works today)

Replace [PUBLISHED-SHA256] with the checksum on the pack page.

Check the SHA-256 Python

import hashlib

expected = "[PUBLISHED-SHA256]"
with open("my-genome.agf.json", "rb") as fh:
    actual = hashlib.sha256(fh.read()).hexdigest()
print("Matches the published checksum" if actual == expected else f"Does NOT match. This file is {actual}")

2. Import with preview and consent

The script sends the file to the workspace preview route, prints what would happen, and applies it only if you type yes. It can then undo it. It uses the same routes as the REST guide.

Import with plain HTTP (works with the flags on) Python

import json
import urllib.request

BASE = "[YOUR-INTELLINIX-API]"
API_KEY = "[YOUR-API-KEY]"


def post(path, body=b""):
    request = urllib.request.Request(
        BASE + path,
        data=body,
        method="POST",
        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    )
    with urllib.request.urlopen(request) as response:
        return json.load(response)


with open("my-genome.agf.json", "rb") as fh:
    preview = post("/genome/workspace/import/preview", fh.read())

print(preview["status"], preview["counts"])
print("skipped:", preview["skipped"])
print("rejected:", preview["rejected"])

if input("Apply this import? Type yes to apply: ").strip().lower() == "yes":
    done = post(f"/genome/transfers/{preview['id']}/consent")
    print(done["status"], done["counts"])
    if input("Undo it again? Type yes to undo: ").strip().lower() == "yes":
        undone = post(f"/genome/transfers/{preview['id']}/undo", json.dumps({"confirm_later_changes": False}).encode())
        print(undone["status"])

The SDK form of the same flow, for when its routes exist. It does not work today:

SDK import methods (not available yet) Python

# NOT AVAILABLE YET. These three methods exist in the Python SDK, but the platform routes they call
# are not mounted, so each call raises NotFoundError (404). Use the plain HTTP script instead.
import json

from intellinix_sdk import Intellinix

client = Intellinix(api_key="[YOUR-API-KEY]", base_url="[YOUR-INTELLINIX-API]")

with open("my-genome.agf.json", encoding="utf-8") as fh:
    agf = json.load(fh)

preview = client.genome.import_preview("[YOUR-AGENT-SLUG]", agf)
transfer_id = preview["id"]
# client.genome.import_consent(transfer_id)
# client.genome.import_undo(transfer_id)

3. Read a genome from your own code

This part of the SDK works today, for an agent of your workspace, through the public API. It reads or compiles the genome that is already there. Whether genes you imported show up for a given agent depends on the layer they went to, so check the result of get after an import.

Read and compile a genome with the SDK Python

from intellinix_sdk import Intellinix

client = Intellinix(api_key="[YOUR-API-KEY]", base_url="[YOUR-INTELLINIX-API]")

view = client.genome.get("[YOUR-AGENT-SLUG]")
print(view.version, len(view.genes))

compiled = client.genome.compile("[YOUR-AGENT-SLUG]", "Draft a polite payment reminder")
print(compiled.compile_id)
print(compiled.section)

Expected results

Verify: one line, “Matches the published checksum” or “Does NOT match” with the file's own checksum.
Import script: the transfer's status (previewed) and counts, then the skipped and rejected lists. After yes, the status is applied; after an undo, undone.
get: an object with version and a list of genes. compile: an object with compile_id and section, the text to put in your prompt.

Troubleshooting

NotFoundError on an SDK import method. Expected today: the routes are not mounted. Use the HTTP script.
ScopeError (403) on an SDK genome call. The key lacks the scope, or it is an older key without a scopes field. Create a new key with the genome scopes.
urllib.error.HTTPError in the script. Read the status in the table below.

HTTP answers from the import routes
Answer	What it means	What to do
401	The credentials were not accepted.	Check the key or token. A suspended or deleted account is refused with 403.
404	Not found. The same answer is used when a feature flag is off, when the agent or transfer id does not exist, and when it belongs to another workspace.	Ask a workspace administrator to turn on agent_genome and genome_format. Check the agent id or transfer id.
403	You are not allowed. The import routes need the settings update permission (an administrator). Applying a preview that holds personal-layer genes is allowed only for the administrator who made it.	Use an administrator account, and apply with the same account that made the preview.
422	The file was rejected, or nothing in it can be imported. The message starts with a code such as too_large, invalid_json, invalid_agf_version, unsupported_agf_major, invalid_document, forbidden_reference or digest_mismatch. Nothing is stored for a rejected file.	See the common problems table on the install page, then fix the file and preview again.
409	The step cannot happen now: the memory changed since the preview (stale), the preview is older than 7 days (expired), the transfer is not in a state that allows the step (invalid_transition, for example applying twice), or the memory changed while applying (conflict, and none of the import is kept).	Preview the file again, then apply.
409 on undo	Lists changed after the import. The answer has code later_changes and a count, and nothing is written.	Read the warning. To undo anyway, send the undo again with confirm_later_changes set to true.