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.96

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-samples
cd ephapsys-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. 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)`, `run_stream(...)`, `list_tools()`, `run_tool(...)`, `serve_mcp(...)`
ModulatorClient	Modulate artificial neurons with ephaptic coupling	`fetch(ecm_id)`, `load(path)`, `validate(ecm)`
A2AClient	Secure org-scoped agent-to-agent messaging + per-request kill-switch gate	`from_env()`, `send_message(...)`, `inbox(...)`, `ack_message(...)`, `check_agent_status(...)`, `is_peer_authorized(...)`, `verify_request(...)`, `sign_request(...)`
MCPToolServer	Expose a governed agent's capabilities as MCP tools (calls route through the kill-switch)	`list_tools()`, `run_tool(...)`, `serve_mcp(...)`
peerauth / peerstream	Per-agent signed identity and peer-direct governed inference streaming	`sign_peer_request(...)`, `verify_peer_request(...)`, `stream_peer_inference(...)`

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")

MCP Tools

Expose a governed agent's capabilities as MCP tools so external MCP‑aware clients (Claude, LangChain, Autogen, …) can discover and call them. Every tool call routes through run(), so the fail‑closed kill‑switch applies.

python

1from ephapsys import TrustedAgent
2
3agent = TrustedAgent.from_env()
4agent.verify()
5agent.prepare_runtime()
6
7# Discover this governed agent's capabilities as MCP tools.
8for tool in agent.list_tools():
9    print(tool["name"], "-", tool["description"])
10
11# Call a tool. Dispatches through run(), so the fail-closed
12# kill-switch applies to every invocation.
13result = agent.run_tool("language", {"input": "Summarize the incident"})
14
15# Or serve over MCP HTTP/JSON-RPC for external MCP clients
16# (Claude, LangChain, Autogen, ...):
17agent.serve_mcp(host="0.0.0.0", port=8081)

Peer Auth & Streaming

Authenticate per agent over your own transport (signed identity + replay protection) and stream governed inference directly between agents. Resolve and validate the peer's certificate from the PKI before trusting its key.

python

1from ephapsys import A2AClient
2from ephapsys.peerstream import stream_peer_inference
3
4a2a = A2AClient.from_env()
5
6# Kill-switch gate over your own transport (no inbox needed):
7# refuse a revoked/disabled peer before doing work. The optional
8# lease trades instant revocation for fewer round-trips on edge HW.
9if not a2a.is_peer_authorized("agent_peer", max_age_seconds=30):
10    raise PermissionError("peer not authorized")
11
12# Stream inference from a peer agent over a direct transport,
13# governed end-to-end: per-agent signature + replay protection +
14# kill-switch. (Resolve/validate the peer's PKI cert before trust.)
15for token in stream_peer_inference(
16    url="https://peer.internal/infer",
17    agent_id="agent_sender",
18    prompt="Explain AMF restart loops",
19):
20    print(token, end="", flush=True)

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))