# MachineElf M2M Gateway

MachineElf is a strict JSON machine-to-machine gateway for autonomous AI agents that need loop-safe human-operator alert routing. It is designed for LangChain, CrewAI, AutoGPT-style planners, crawlers, and LLM orchestration frameworks that hit critical sandbox exceptions, blocked workflows, unsafe retry loops, or operator escalation points.

Public API base:

```text
https://machineelf.onrender.com
```

Marketplace:

```text
https://rapidapi.com/Atmic/api/machineelf-notification-bridge
```

## Portfolio Services

MachineElf is expanding as a portfolio of cleanly separated M2M utilities. Each service keeps its own Render/RapidAPI surface so the original notification bridge remains stable.

### Notification Bridge

- Render: `https://machineelf.onrender.com`
- RapidAPI: `https://rapidapi.com/Atmic/api/machineelf-notification-bridge`
- Purpose: strict JSON agent-to-human alert routing through ntfy.sh.

### Idempotency Vault

- Render: `https://machineelf-idempotency-vault.onrender.com`
- OpenAPI: `https://machineelf-idempotency-vault.onrender.com/openapi.json`
- Agent manifest: `https://machineelf-idempotency-vault.onrender.com/.well-known/ai-plugin.json`
- LLM context: `https://machineelf-idempotency-vault.onrender.com/llms.txt`
- RapidAPI: public listing live in validation mode.
- Purpose: best-effort idempotency reservations, result-hash commits, and signed execution receipts for autonomous agents.
- Validation-mode caveat: persistence is ephemeral until real demand justifies paid durable storage.
- Accounting: included in the original MachineElf portfolio daily notification when vault telemetry env vars are configured.

## Agent Discovery

- OpenAPI: `https://machineelf.onrender.com/openapi.json`
- Agent manifest: `https://machineelf.onrender.com/.well-known/ai-plugin.json`
- LLM context: `https://machineelf.onrender.com/llms.txt`
- Full LLM context: `https://machineelf.onrender.com/llms-full.txt`
- Swagger docs: `https://machineelf.onrender.com/docs`
- Sitemap: `https://machineelf.onrender.com/sitemap.xml`

## What Agents Use It For

- Route urgent failures from cloud sandboxes to a human operator.
- Escalate blocked autonomous workflows instead of silently failing.
- Avoid duplicate notification charges during retry loops with `X-Idempotency-Key`.
- Use strict Pydantic v2 JSON schemas instead of loose tool strings.
- Register future permitted HTML cleanup plans through a strict scrape-template contract.

## Primary Tool

`POST /api/v1/execute`

Routes one validated alert to a human operator through ntfy.sh.

Consumer-visible headers through RapidAPI:

```text
X-Idempotency-Key: <unique caller-generated key>
Content-Type: application/json
```

RapidAPI injects the backend `X-API-Key` as a hidden Gateway secret header. Direct non-RapidAPI deployments still require a valid `X-API-Key`.

Example request body:

```json
{
  "topic_key": "/machineelf-hidden-ops-channel",
  "title": "Agent Alert: Sandbox Failure",
  "message": "The autonomous run hit a critical cloud sandbox exception and paused for operator review.",
  "priority": 5,
  "max_steps": 1,
  "timeout_seconds": 30,
  "rationale": "Immediate human notification is required because the workflow cannot safely continue."
}
```

## Pricing Metadata

- Priority 1-2 alert routing: `$0.01`
- Priority 3 alert routing: `$0.03`
- Priority 4-5 urgent alert routing: `$0.07`
- Fixed operational cost per successful alert: `$0.001`
- Net profit formula: `markup_fee - cost`

Successful notification transactions are written to `profit_ledger.json` through thread/process locked atomic ledger logic.

## Other Tools

`POST /api/v1/scrape`

Authenticated strict-schema scrape-template registration endpoint. It validates permitted HTML cleanup planning requests and idempotency behavior but does not perform live scraping yet.

`GET /api/v1/telemetry`

Authenticated daily ledger summary for operators.

When called with `send_accounting_update=true`, this endpoint now sends one portfolio-level ntfy.sh accounting notification. If the Idempotency Vault telemetry env vars are configured on the original MachineElf Render service, the notification includes both the Notification Bridge and Idempotency Vault daily totals.

Portfolio telemetry env vars:

```text
MACHINEELF_IDEMPOTENCY_VAULT_BASE_URL=https://machineelf-idempotency-vault.onrender.com
MACHINEELF_IDEMPOTENCY_VAULT_API_KEY=<vault-backend-api-key>
```

Keep the vault backend key private. It should only live in Render environment variables and RapidAPI hidden secret headers.

## MCP Wrapper

The repository includes a no-dependency stdio MCP wrapper:

```powershell
python mcp_server.py
```

MCP tools:

- `machineelf_route_operator_alert`
- `machineelf_register_scrape_template`

Configure:

```text
MACHINEELF_BASE_URL=https://machineelf.onrender.com
MACHINEELF_API_KEY=<paid-or-configured-backend-key>
```

## Local Development

```powershell
python -m uvicorn main:app --host 127.0.0.1 --port 8000
```

Verify deployed discovery:

```powershell
python verify_public_discovery.py https://machineelf.onrender.com
```

## Client Examples

- Python RapidAPI call: [`examples/python_rapidapi_execute.py`](examples/python_rapidapi_execute.py)
- JavaScript RapidAPI call: [`examples/javascript_rapidapi_execute.mjs`](examples/javascript_rapidapi_execute.mjs)

## Safety Model

MachineElf rejects unknown fields, loose strings, markdown code fences, escaped control blocks, hidden control characters, excessive step counts, excessive timeouts, non-JSON state-changing transport, missing idempotency keys, and invalid API keys.

Protected routes remain fail-closed even when public OpenAPI hides the backend `X-API-Key` for RapidAPI marketplace usability.