Hyphae
GitHub

SDKs

Two SDKs cover Hyphae's format-1 (v1) and Native v2 APIs: Python (hyphae-sdk) and TypeScript (@hyphae_/hyphae). Both talk to the same local binary protocol (HYPHLCL1) or the loopback-first HTTP /v2 adapter that hyphae serve exposes. In Rust, skip the wire protocol entirely and embed hyphae-native-product directly — engine-to-engine calls are typed Rust, not HTTP or JSON.

Both SDKs are source-only in 3.0.0. Per the release receipt's distribution boundary, neither is published to a package registry: hyphae-sdk is not on PyPI, and @hyphae_/hyphae is not on npm. Use them from the repository source tree. (The unrelated hyphae package already on PyPI is not this project.)

Python

hyphae-sdk requires Python 3.11+, uses only the standard library at runtime, and ships typed generated models with a py.typed marker. The v1 client is synchronous; Native v2 adds an async adapter with one owned serial worker. 

from pathlib import Path
from hyphae_sdk.v2 import HyphaeClient

api_key = Path("owner.key").read_text(encoding="ascii").strip()

# Local transport (UDS / named pipe), authenticated in the HELLO trailer
with HyphaeClient.local_authenticated("./hyphae.sock", api_key) as client:
    rows = client.sql("SELECT id, body FROM notes WHERE id = ?", [2])
    # → {'kind': 'rows', 'columns': ['id','body'], 'rows': [[2, 'second note with proofs']]}
    value = client.structure_get(b"session:active")   # structure keys are bytes!
    status = client.security_status()

# Same API over HTTP v2
with HyphaeClient.http("http://127.0.0.1:8791", bearer_token=api_key) as client:
    caps = client.capabilities()

Structure keys and values are bytes — passing str raises ClientError. Python integers preserve Hyphae's full signed 64-bit document domain; floating-point JSON is rejected outright rather than silently truncated.

hyphae_sdk.v2.HyphaeClient methods, by area:

  • SQL — sql, prepare_sql, execute_prepared, deallocate_prepared
  • Structures — structure_get, structure_set, structure_ttl, structure_mutate, structure_read
  • Search — search, search_collection, search_ingest, search_document_update, search_document_delete
  • Transactions — transaction_status, transaction_begin, the four transaction_stage_* methods, transaction_commit, transaction_rollback
  • Proofs — verify_proof, prove, prove_sql
  • Backup/restore — backup, restore
async with AsyncHyphaeClient.local_authenticated(endpoint, api_key) as client:
    async with await client.begin_transaction() as tx:
        await tx.stage_sql("INSERT INTO jobs VALUES (1, 'ready')")
        await tx.stage_structure({"kind": "string_set",
            "key": {"keyspace": 3, "key": b"job:1"}, "value": b"ready"})
        await tx.commit()

A transaction abandoned by its context manager rolls back; an uncertain commit is terminal outcome_unknown and is resolved through the transaction-status operation, never by re-sending the commit — see Transactions and proofs.

TypeScript

@hyphae_/hyphae requires Node.js 20+, uses the runtime fetch, and has no runtime package dependencies. The v1 client mirrors Python's method list (capabilities, put, get, query, retrieveHybrid, and so on); Native v2 exposes the same surface as Python's, camelCased:

  • SQL — sql, prepareSql, executePrepared, deallocatePrepared
  • Structures — structureGet, structureSet, structureTtl, structureMutate, structureRead
  • Search — search, searchCollection, searchIngest, searchDocumentUpdate, searchDocumentDelete
  • Transactions — transactionStatus, transactionBegin, the four transactionStage* methods, transactionCommit, transactionRollback
  • Proofs — verifyProof, prove, proveSql
  • Backup/restore — backup, restore

Hyphae documents use signed 64-bit integers. The codec returns safe values as number and larger values as bigint; serialization rejects an unsafe number rather than losing precision silently: 

await client.put({
  records: [{ key_hex: "6d6178", value: 9223372036854775807n }],
});

The codec's 3.0.0 search coverage: relative-score fusion, autocut knee truncation, range facets, lexical minimum-match, a per-branch vector max_distance, highlighting, fuzzy/prefix/ phrase queries, BM25F field boosts, and offset pagination over the final ranking — the same feature set described in Search.

Protocol minor: 5 vs 6

A managed Python local session negotiates Native local protocol minor 5, with minors 3 through 5 supported (hyphae_sdk.v2.protocol.PROTOCOL_MINOR and PROTOCOL_MINORS_SUPPORTED). The TypeScript SDK's codec speaks minor 6. Minor 6 is the revision that adds the seven Valkey-shaped structure mutations and six typed reads described in Keyspace — if a workflow needs those specific operations over the SDK layer rather than the CLI's raw JSON envelopes, reach for the TypeScript client, or use the CLI directly with either SDK.

The HTTP /v2 loopback surface

Both SDKs' Native v2 clients work identically over the local socket or over HTTP: HyphaeClient.local(endpoint) / HyphaeClient.local_authenticated(...) carries exact HYPHLCL1 frames over AF_UNIX or a Windows named pipe; HyphaeClient.http(origin) carries the same canonical product envelopes at POST /v2/execute. A bearer credential may use plain http:// only against a canonical loopback host (127.0.0.0/8, [::1], or exact localhost); every other origin requires https:// and is rejected before the request can carry the key. There is no plain GET /v2/capabilities — use a client method, not a hand-rolled request.

JS framework adapters

Framework adapters are optional consumers, never core dependencies — omit them and the host application behaves exactly as before. The JavaScript adapters remain source packages in the repository until they receive an independent registry release, under @hyphae_/hyphae-integrations: 

// Astro — attaches a client to Astro.locals.hyphae
import { createHyphaeAstroMiddleware } from "@hyphae_/hyphae-integrations/astro";
export const onRequest = createHyphaeAstroMiddleware({
  baseUrl: "http://127.0.0.1:8787",
});

// Next — server components and route handlers only, never NEXT_PUBLIC_*
import { createHyphaeNextClientFromEnv } from "@hyphae_/hyphae-integrations/next";
const client = createHyphaeNextClientFromEnv();

// Vite — dev-server proxy plugin plus a separate browser-side client
import { hyphaeVite } from "@hyphae_/hyphae-integrations/vite";
export default defineConfig({ plugins: [hyphaeVite({ target: "http://127.0.0.1:8787" })] });

The Astro middleware refuses to overwrite existing host state. The Next adapter is server-only by design — keep HYPHAE_BASE_URL and HYPHAE_BEARER_TOKEN private. The Vite browser client (@hyphae_/hyphae-integrations/vite/client) reaches the versioned /v1 surface through the same origin and cannot accept a bearer token — production proxying is the deployment host's responsibility, not the adapter's.