Ephapsys

Documentation

Use Ephapsys to securely manage the full lifecycle of your AI agents and their models.

Boost performance, provision with trust, enforce secure inference, and maintain audit-grade governance.

Snippets mirror the samples in the official github repo.

Install the SDK & CLI v0.2.20

bash

# Lightweight runtime (orchestration/auth/bundles)
pip install ephapsys

# Optional feature groups
pip install "ephapsys[modulation]"   # model loading/inference stack
pip install "ephapsys[eval]"         # evaluation tooling
pip install "ephapsys[audio]"        # audio I/O support
pip install "ephapsys[vision]"       # vision/camera support
pip install "ephapsys[all]"          # full SDK dependency set

API Reference (Python)

High-level classes and core methods.

Class	Purpose	Key Methods
TrustedAgent	Manage signed model packages and secure lifecycle	`from_package(path, org_id)`, `bind(hardware, tpm?)`, `register(pki, metadata?)`, `verify(pki)`, `is_revoked(pki)`, `session(enforce)`
ModulatorClient	Modulate artificial neurons with ephaptic coupling	`fetch(ecm_id)`, `load(path)`, `validate(ecm)`
A2AClient	Send and receive secure org-scoped agent-to-agent messages	`from_env()`, `send_message(...)`, `inbox(...)`, `ack_message(...)`

Modulation

Launch ephaptic modulation jobs to tune activation fields toward a KPI without retraining or exposing raw checkpoints.

python

1from ephapsys.modulation import ModulatorClient
2import os
3
4mc = ModulatorClient.from_env()
5mc.start_job(
6    model_template_id,
7    variant="additive",
8    kpi=kpi,
9    mode="auto",
10    dataset=dataset,
11    search=search,
12)
13tpl, job_id = mc.wait_for_job_id(model_template_id)
14print("job:", job_id)

Provision

Provision a signed agent package and bind it to trusted hardware.

python

1# Personalize + bind to trusted anchor
2import os
3from ephapsys import TrustedAgent
4
5agent = TrustedAgent.from_env()
6anchor = os.getenv("PERSONALIZE_ANCHOR", "tpm")
7
8result = agent.personalize(anchor=anchor)
9agent.prepare_runtime()
10print("Agent personalized via", result.get("anchor", anchor))

Verify & Enforce

Verify integrity, certificate chain, revocation state, and host binding. Then wrap inference in an enforcement session.

python

1# Verify + wrap inference in an enforcement session
2ok, report = agent.verify()
3if not ok:
4    raise RuntimeError(f"Agent blocked: {report}")
5
6with agent.session(lease_seconds=1800) as session:
7    reply = agent.run("Hello, world!", model_kind="language")
8    print("response:", reply)

A2A

Exchange signed, org-scoped agent-to-agent messages with replay protection and acknowledgements.

python

1from ephapsys import A2AClient
2
3# .env:
4# AOC_BASE_URL=https://api.ephapsys.com
5# AOC_A2A_TOKEN=a2a_xxx
6# AOC_ORG_ID=org_xxx
7# A2A_SIGN_REQUESTS=1
8# A2A_HMAC_SECRET=replace_with_org_secret
9
10a2a = A2AClient.from_env()
11
12sent = a2a.send_message(
13    from_agent_id="agent_sender",
14    to_agent_id="agent_receiver",
15    payload={"op": "ping"},
16    message_type="event",
17    correlation_id="corr-123",
18)
19
20inbox = a2a.inbox(agent_id="agent_receiver", limit=20)
21for msg in inbox.get("items", []):
22    a2a.ack_message(message_id=msg["id"], agent_id="agent_receiver")

Secure Inference

Perform inference through a policy‑enforced session. Violations block execution.

python

1# Secure inference (policy-enforced)
2ok, _ = agent.verify()
3if not ok:
4    raise RuntimeError("Agent disabled or revoked")
5
6agent.prepare_runtime()
7result = agent.run(
8    input_data="Hello, world!",
9    model_kind="language",
10)
11print(result)

Optional: for edge CPU deployments, you can use GGUF artifacts with llama.cpp. This adds to the default Transformers path and does not replace it.

python

1# Optional GGUF / llama.cpp runtime (edge CPU)
2# The SDK auto-detects .gguf artifacts in prepared runtime.
3# Use one of these runtime providers:
4# 1) pip install llama-cpp-python
5# 2) install llama-cli and set AOC_LLAMA_CPP_CLI
6
7import os
8os.environ.setdefault("AOC_LLAMA_CPP_CLI", "llama-cli")
9os.environ.setdefault("AOC_GGUF_CTX", "2048")
10os.environ.setdefault("AOC_GGUF_MAX_NEW_TOKENS", "256")
11
12agent = TrustedAgent.from_env()
13rt = agent.prepare_runtime()
14lang = rt.get("language", {})
15print("gguf detected:", bool(lang.get("gguf_path")))
16print(agent.run("Hello from GGUF", model_kind="language"))

Revocation

Revoke agents that fail attestation or violate policy. Enforced on next verification.

python

1# Revoke certificates for a compromised agent
2resp = agent.revoke_certificates(reason="compromised_host")
3print("revoked:", resp.get("revoked", 0))