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.

AOC stands for Agent Ops Center. It is the Ephapsys control plane where you retrieve org credentials, register model and agent templates, and monitor modulation jobs. Sign in or sign up to access the portal.

Snippets mirror the samples in the official github repo.

Install the SDK & CLI v0.2.65

bash

# Default SDK install (agent runtime + language/modulation stack)
pip install ephapsys

# Optional feature groups
pip install "ephapsys[audio]"        # audio I/O support
pip install "ephapsys[vision]"       # vision/camera support
pip install "ephapsys[embedding]"    # vector search / embeddings
pip install "ephapsys[eval]"         # evaluation tooling
pip install "ephapsys[all]"          # full SDK dependency set

Quickstart

The supported first-run path for HelloWorld is the repo-backed ./quickstart.sh workflow, not a bare Python snippet. It provisions or reuses starter templates, writes template IDs back into .env, and then launches the sample.

bash

git clone https://github.com/Ephapsys/ephapsys-sdk
cd ephapsys-sdk/samples/agents/helloworld
cp .env.example .env

# Fill in the required values in .env:
# - AOC_BASE_URL=https://api.ephapsys.com
# - AOC_ORG_ID=org_xxx
# - AOC_PROVISIONING_TOKEN=boot_xxx
# - AOC_MODULATION_TOKEN=mod_xxx

./quickstart.sh

If you read from a local .env file in custom Python scripts, load it explicitly before calling TrustedAgent.from_env().

python

1pip install ephapsys python-dotenv
2
3from dotenv import load_dotenv
4from ephapsys import TrustedAgent
5
6load_dotenv()
7agent = TrustedAgent.from_env()

Credentials & Environment

Retrieve credentials from the AOC portal in Organization → Tokens. Provisioning tokens start with boot_, modulation tokens start with mod_, and A2A tokens are optional unless you are enabling agent-to-agent messaging.

Script references such as ./quickstart.sh, ./push.sh, and ./run.sh apply to the sample agents in the SDK repo, especially HelloWorld and Robot. They are convenience workflows, not generic SDK commands required by every integration.

Variable	Required?	Where / Notes
AOC_BASE_URL	Required	`https://api.ephapsys.com`
AOC_ORG_ID	Required	Found in the AOC portal after signup under your organization.
AOC_PROVISIONING_TOKEN	Required	Found in the AOC portal under Organization → Tokens. Starts with `boot_`.
AOC_MODULATION_TOKEN	Required for sample modulation flows	Found in the AOC portal under Organization → Tokens. Starts with `mod_`. Used by sample scripts such as `./push.sh`.
MODEL_TEMPLATE_ID	Optional on first run	Often written automatically by sample scripts such as `./quickstart.sh` or `./push.sh`.
AGENT_TEMPLATE_ID	Optional on first run	Often written automatically by sample scripts such as `./quickstart.sh` or `./push.sh`.
HF_TOKEN	Optional	Only needed for gated or private Hugging Face repos.
AOC_A2A_TOKEN	Optional	Only needed for agent-to-agent messaging.

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 org-scoped agent-to-agent messages with 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
8a2a = A2AClient.from_env()
9
10sent = a2a.send_message(
11    from_agent_id="agent_sender",
12    to_agent_id="agent_receiver",
13    payload={"op": "ping"},
14    message_type="event",
15    correlation_id="corr-123",
16)
17
18inbox = a2a.inbox(agent_id="agent_receiver", limit=20)
19for msg in inbox.get("items", []):
20    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))