Metadata-Version: 2.4
Name: ephapsys
Version: 0.2.14
Summary: Ephapsys helps you empower and govern AI agents.
Author-email: Ephapsys <hello@ephapsys.com>
License: Apache 2.0
Project-URL: Homepage, https://ephapsys.com
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=42.0.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: requests>=2.31.0
Requires-Dist: numpy>=1.23
Requires-Dist: psutil>=5.9.0
Provides-Extra: tpm
Requires-Dist: tpm2-pytss>=2.3.0; sys_platform == "linux" and extra == "tpm"
Provides-Extra: hsm
Requires-Dist: google-cloud-kms>=2.21.0; extra == "hsm"
Provides-Extra: modulation
Requires-Dist: torch>=2.0.0; extra == "modulation"
Requires-Dist: transformers>=4.33.0; extra == "modulation"
Requires-Dist: datasets<3.0.0,>=2.14.0; extra == "modulation"
Requires-Dist: safetensors>=0.4.5; extra == "modulation"
Provides-Extra: audio
Requires-Dist: librosa>=0.10.2.post1; extra == "audio"
Requires-Dist: soundfile>=0.12.1; extra == "audio"
Provides-Extra: eval
Requires-Dist: evaluate>=0.4.1; extra == "eval"
Requires-Dist: bert-score>=0.3.13; extra == "eval"
Requires-Dist: sacrebleu>=2.3.1; extra == "eval"
Requires-Dist: rouge-score>=0.1.2; extra == "eval"
Requires-Dist: jiwer>=3.0.3; extra == "eval"
Provides-Extra: vision
Requires-Dist: Pillow>=9.5.0; extra == "vision"
Requires-Dist: opencv-python-headless>=4.8.0; extra == "vision"
Provides-Extra: video
Requires-Dist: Pillow>=9.5.0; extra == "video"
Requires-Dist: opencv-python-headless>=4.8.0; extra == "video"
Provides-Extra: embedding
Requires-Dist: sentence-transformers>=2.2.2; extra == "embedding"
Requires-Dist: faiss-cpu>=1.7.4; extra == "embedding"
Provides-Extra: all
Requires-Dist: google-cloud-kms>=2.21.0; extra == "all"
Requires-Dist: torch>=2.0.0; extra == "all"
Requires-Dist: transformers>=4.33.0; extra == "all"
Requires-Dist: datasets<3.0.0,>=2.14.0; extra == "all"
Requires-Dist: safetensors>=0.4.5; extra == "all"
Requires-Dist: librosa>=0.10.2.post1; extra == "all"
Requires-Dist: soundfile>=0.12.1; extra == "all"
Requires-Dist: evaluate>=0.4.1; extra == "all"
Requires-Dist: bert-score>=0.3.13; extra == "all"
Requires-Dist: sacrebleu>=2.3.1; extra == "all"
Requires-Dist: rouge-score>=0.1.2; extra == "all"
Requires-Dist: jiwer>=3.0.3; extra == "all"
Requires-Dist: Pillow>=9.5.0; extra == "all"
Requires-Dist: opencv-python-headless>=4.8.0; extra == "all"
Requires-Dist: sentence-transformers>=2.2.2; extra == "all"
Requires-Dist: faiss-cpu>=1.7.4; extra == "all"
Requires-Dist: webrtcvad>=2.0.10; extra == "all"
Requires-Dist: sounddevice>=0.4.6; extra == "all"
Requires-Dist: pyaudio>=0.2.14; extra == "all"
Requires-Dist: tpm2-pytss>=2.3.0; sys_platform == "linux" and extra == "all"

# Ephapsys SDK

Lightweight SDK for **EC-ANN modulation**, **trusted agent provisioning**, and **runtime security**.


---

## 📦 Installation

```bash
pip install ephapsys
```

Optional feature groups:
```bash
pip install "ephapsys[modulation]"
pip install "ephapsys[audio]"
pip install "ephapsys[eval]"
pip install "ephapsys[vision]"      # alias: [video]
pip install "ephapsys[all]"
```

Choose the profile by workload:

| Workload | Install command |
|---|---|
| Lightweight orchestrator/proxy only | `pip install ephapsys` |
| Agent runtime (HelloWorld language) | `pip install "ephapsys[modulation]"` |
| Agent runtime (Robot multimodal) | `pip install "ephapsys[modulation,audio,vision,embedding]"` + `pip install webrtcvad sounddevice pyaudio` |
| Modulators/training scripts | `pip install "ephapsys[modulation]"` |
| Modulators with full evaluation/report stack | `pip install "ephapsys[all]"` |

---

## 🚀 Quickstart

```python
from ephapsys import TrustedAgent

agent = TrustedAgent.from_env()

ok, report = agent.verify()
if not ok:
    raise RuntimeError(f"Agent blocked: {report}")

agent.prepare_runtime()
print(agent.run("Hello world", model_kind="language"))
```

---

## ⚙️ Environment Variables

| Variable              | Description                                         |
|-----------------------|-----------------------------------------------------|
| `EPHAPSYS_AGENT_ID`   | Agent ID/label assigned by AOC                      |
| `AOC_BASE_URL`        | API endpoint, e.g. `http://localhost:8000`          |
| `AOC_ORG_ID`          | Org identifier (non-secret tenant scope)            |
| `AOC_BOOTSTRAP_TOKEN` | Bootstrap credential exchanged for short-lived token |
| `AOC_API_KEY`         | Deprecated compatibility path                        |
| `EPHAPSYS_STORAGE_DIR`| Optional, defaults to `.ephapsys_state`             |

`AOC_API_KEY` is being deprecated in favor of `AOC_ORG_ID` + `AOC_BOOTSTRAP_TOKEN`.
For edge production, use hardware anchors (`tpm`, `tee`, `dsim`, `hsm`) and avoid `PERSONALIZE_ANCHOR=none`.

---

## 🎛️ ModulatorClient

Start / iterate / complete modulation on **model templates**:

```python
from ephapsys.modulation import ModulatorClient

mod = ModulatorClient(api_base="http://localhost:7001", api_key="dev")
resp = mod.start_job(
    model_template_id="google/gemma-2b",
    variant="ec-ann",
    search_space={"lr": [1e-3, 1e-4]},
    kpi={"accuracy": "max"},
    mode="auto"
)
print(resp)
```

---

## 🖥️ CLI

The SDK includes a CLI (`ephapsys`) for working with agents, models, modulation, and certificates.  
Authentication is required before most commands.

### 🔑 Login

```bash
ephapsys login --username izzo
Password: ****
✅ Logged in.
```

This stores a JWT in `~/.ephapsys_state/session.json`.

---

### 📦 Models

Register, list, and remove models tied to your org.

```bash
# Register
ephapsys model register --provider huggingface --ids google/gemma-2b
ephapsys model register --provider huggingface --ids google/embeddinggemma-300m  google/flan-t5-base
ephapsys model register --provider huggingface --ids microsoft/speecht5_tts
ephapsys model register --provider huggingface --ids google/gemma-2b google/embeddinggemma-300m  microsoft/speecht5_tts

# List (pretty table)
ephapsys model list
name                 provider     status
-----------------------------------------
google/gemma-2b      huggingface  registered
google/embedding...  huggingface  registered

# List (JSON)
ephapsys model list --json

# Remove
ephapsys model remove --provider huggingface --id google/gemma-2b
```

---

### 🤖 Agents

```bash
# List (pretty table)
ephapsys agent list
agent_id     label        status
--------------------------------
agent-123    Sales Bot    registered
agent-456    SupportBot   enabled

# List (JSON)
ephapsys agent list --json
```

Other agent commands (`verify`, `enable`, `disable`, `revoke`, `export-manifest`) are also available.

---

### 📊 Modulation

```bash
# Start job
ephapsys mod start --model-template-id google/gemma-2b --variant ec-ann   --search-space '{"lr":[1e-3,1e-4]}' --kpi '{"accuracy":"max"}'

# Report metrics
ephapsys mod metrics --job-id JOB123 --metrics '[{"step":1,"val":0.84}]'

# Request next step
ephapsys mod next --job-id JOB123 --last-metrics '[{"step":1,"val":0.84}]'

# Complete job
ephapsys mod complete --job-id JOB123 --artifacts '{"weights":"s3://..."}'
```


---

## 🧪 Samples

Access the samples at: [https://github.com/ephapsys](https://github.com/ephapsys)
