klickd

Official Python library for reading and writing .klickd portable AI context files.

One soul. Any model. Any agent. — open-source security and continuity layer for every actor in AI.

Official page for the open .klickd format → klickd.app/klickdskill

Install

pip install klickd

Quick start

Load (decrypt) a .klickd file

from klickd import load_klickd

with open("context.klickd", "rb") as f:
    payload = load_klickd(f.read(), passphrase="my-passphrase")

print(payload["identity"]["name"])
print(payload["memory"])

Save (encrypt) a .klickd file

from klickd import save_klickd

payload = {
    "payload_schema_version": "3.0.0",
    "domain_schema_version": "1.0.0",
    "identity": {"name": "Alice", "language": "en", "timezone": "Europe/Luxembourg"},
    "agent_instructions": "Be concise.",
    "memory": [],
}

klickd_bytes = save_klickd(payload, passphrase="my-passphrase", domain="education")

with open("context.klickd", "wb") as f:
    f.write(klickd_bytes)

Legacy v2.x files (PBKDF2)

payload = load_klickd(file_bytes, passphrase="my-passphrase", legacy=True)

.klickd v4 — GA strict + preview fields

This library targets the v3 envelope on the wire (envelope crypto contract is frozen at v3 per SPEC.md §33.10 #2) and ships the v4 GA strict candidate payload schema for validation. The v4 preview track (v4.0.0-preview.1) remains accepted in parallel.

The v4 additive payload fields — profile_kind, media_profile, verification_gates, human_veto_policy, claim_sources, verification_artifacts, migration, context_cost, deprecated_fields — are preserved verbatim on round-trip (SPEC.md §33.7). load_klickd returns the raw decrypted JSON object; save_klickd re-encrypts it without filtering unknown keys.

Optional v4 schema validation

Install the optional validate extra to enable strict / preview schema validation against the bundled v4 JSON schemas (RFC-001 v1, RFC-002 v1 core, RFC-004 v1):

pip install klickd[validate]

from klickd import validate, validate_iter_errors

payload = {
    "payload_schema_version": "4.0",
    "verification_gates": {
        "version": 1,
        "gates": [
            {"action_class": "public_post", "level": "block"},
        ],
    },
}

validate(payload, strict=True)  # raises KlickdError(KLICKD_E_SCHEMA) on fail

# Non-raising variant that returns every (path, message):
errors = validate_iter_errors(payload, strict=True)

validate(..., strict=False) selects the permissive v4 preview schema. validate(..., target="unified") selects the unified envelope+payload schema. The strict schema accepts both "4.0" and "4.0.0-preview.1" in payload_schema_version so preview files round-trip without rewriting.

v4_preview_payload = {
    "payload_schema_version": "4.0.0-preview.1",
    "domain_schema_version": "1.0.0",
    "profile_kind": "learner",
    "verification_gates": {"public_post": "confirm"},
    # ... any additional v4 preview fields are preserved on save/load
}
recovered = load_klickd(save_klickd(v4_preview_payload, "passphrase"), passphrase="passphrase")
assert recovered == v4_preview_payload

See SPEC.md §33 and examples/v4-preview/ for the preview-track details.

Starter .klickd skills (v4.0 envelope — non-normative)

Four real, structured, downloadable starter .klickd skills ship under examples/v4/starter-skills/:

• user.klickd — x.klickd/user (transversal base)
• student.klickd — x.klickd/student (education)
• research.klickd — x.klickd/research (research / evidence discipline)
• coding.klickd — x.klickd/coding (software engineering)

Each skill carries base_transversal_core, framework-anchored competencies[] (ESCO / DigComp / LifeComp / EQF / CEFR / SFIA), levels[], mastery[] (pointer-only), source_policy, evidence_policy, verification_gates, human_authority, and a structured_memory slice scoped to memory.x_klickd.<pack>. They are non-normative and trigger no release. SHA-256 manifest in manifest.json; offline verifier scripts/verify_starter_skills.py.

Bundled in klickd 4.0.1

Starting with klickd 4.0.1 (a packaging-only patch — the stable spec release remains v4.0.0), these four starter .klickd skills ship inside the wheel and sdist as klickd/starter_skills/*.klickd and are accessible via a small helper API. The on-the-wire .klickd format, the bundled JSON schemas, and the spec are unchanged from v4.0.0. This patch ships only the starter skill packaging fix; no new schema material is introduced.

from klickd import (
    list_starter_skills,
    get_starter_skill_bytes,
    get_starter_skills_manifest,
    get_starter_skills_dir,
)

list_starter_skills()
# → ['coding.klickd', 'research.klickd', 'student.klickd', 'user.klickd']

raw = get_starter_skill_bytes("user.klickd")
manifest = get_starter_skills_manifest()
path = get_starter_skills_dir()  # importlib.resources Traversable as str

Cryptographic specification (v3.0)

Error codes

from klickd import KlickdError, KlickdErrorCode

try:
    payload = load_klickd(data, passphrase="wrong")
except KlickdError as e:
    print(e.code)         # KlickdErrorCode.AUTH
    print(e.http_status)  # 401

Links

• Format page: klickd.app/klickdskill
• Specification: SPEC.md
• Repository: github.com/Davincc77/klickdskill
• DOI: 10.5281/zenodo.20383133 (v4.0.0) · concept DOI (all versions): 10.5281/zenodo.20262530
• Homepage: klickd.app/klickdskill

License

CC0 1.0 Universal — Public Domain Dedication.
Author: Vincenzo Cirilli (.klickd / klickd.app, Luxembourg)