diff --git a/docs/GET_STARTED_WITH_X402.md b/docs/GET_STARTED_WITH_X402.md deleted file mode 100644 index 2e7dcc2..0000000 --- a/docs/GET_STARTED_WITH_X402.md +++ /dev/null @@ -1,53 +0,0 @@ -# Get Started with x402 - -This guide explains how to enable and use x402 pay-for-inference with the Ekai Gateway. - -## Overview - -x402 enables onchain, per‑request payments when a target model does not have an API key configured. The gateway automatically handles 402 responses, performs the onchain payment in stablecoins, retries the request with proof, and streams the provider’s response back to your client. - -## Prerequisites - -- Ekai Gateway. -- An EVM wallet private key funded with USDC on Base. - -## Configuration - -Set the following environment variables before starting the gateway: - -``` -# Required for x402 payments -PRIVATE_KEY=0x... # EVM private key with USDC balance on Base -``` - -The gateway automatically uses Ekai's hosted x402 inference URL (`https://x402.ekailabs.xyz`) by default. - -Gateway modes and endpoints are configured via `config.x402` (see logs at startup): -- `config.x402.enabled`: enable or disable x402. -- `config.x402.baseUrl`, `config.x402.chatCompletionsUrl`, `config.x402.messagesUrl`. -- Startup logs indicate `x402-only`, `hybrid`, or `BYOK` mode based on your key/config setup. - -## How It Works - -1. **Initial request**: the gateway sends a normal request to an x402‑enabled endpoint. -2. **402 response**: if payment is required, the server returns HTTP 402 Payment Required with payment parameters. -3. **Automatic payment**: the `x402-fetch` wrapper intercepts the 402, creates the on‑chain payment, and prepares proof. -4. **Request retry**: the original request is retried automatically with the payment proof header. -5. **Service access**: the service validates proof and returns the inference response, which the gateway streams to your client. - -## Client Usage - -Use your existing OpenAI or Anthropic‑compatible clients (Claude Code, Codex) pointed at the gateway. When a chosen model has no API key configured, the gateway routes via x402 automatically; otherwise it uses your configured provider keys directly. - -## Supported via Ekai x402 (Rasta) - -The Ekai x402 endpoint (Rasta) currently supports these providers/models: - -| Provider | /chat/completions | /messages | Pattern | -|----------|-------------------|-----------|---------| -| **OpenRouter** | ✅ | | Any OpenRouter model ID (e.g., `openai/gpt-5`, `moonshotai/kimi-k2-thinking`) | -| **Anthropic** | | ✅ | Models containing `claude` (e.g., `claude-haiku-4-5-20251001`) | -| **xAI** | | ✅ | Models containing `grok` (e.g., `grok-code-fast-1`) | - -Notes: -- Model IDs must follow the provider’s naming (e.g., `/` for OpenRouter, `claude-*` for Anthropic). diff --git a/docs/ROFL_DEPLOYMENT.md b/docs/ROFL_DEPLOYMENT.md deleted file mode 100644 index 325452b..0000000 --- a/docs/ROFL_DEPLOYMENT.md +++ /dev/null @@ -1,147 +0,0 @@ -# ROFL Deployment Guide - -Deploy your own private ekai-gateway instance on Oasis Network using ROFL (Runtime Off-chain Logic). - -## Why ROFL? - -- **Private**: Your API keys stay secure, in a TEE (Trusted Execution Environment) -- **Isolated**: Each user deploys their own instance -- **Verifiable**: Code execution can be verified on-chain - ---- - -## Demo - -{% embed url="https://www.youtube.com/watch?v=sLg9YmYtg64" %} - ---- - -## Prerequisites - -1. **Oasis CLI** (v0.18.x+) - Install from [CLI Reference](https://cli.oasis.io), then verify: - ```bash - oasis --version - ``` - -2. **Docker** - ```bash - docker --version - ``` - -3. **Funded Wallet** - ```bash - oasis wallet create my_wallet - # Get testnet tokens: https://faucet.testnet.oasis.io/ - oasis wallet show my_wallet --network testnet --paratime sapphire - ``` - -4. **API Keys** (at least one): OpenAI, Anthropic, or xAI - -## Deployment - -```bash -# 1. Clone -git clone https://github.com/ekailabs/ekai-gateway.git -cd ekai-gateway - -# 2. Create rofl.yaml from template -cp rofl.yaml.template rofl.yaml - -# 3. Register app -oasis rofl create --network testnet --paratime sapphire - -# 4. Set secrets (at least one) -echo -n "sk-your-openai-key" | oasis rofl secret set OPENAI_API_KEY - -echo -n "sk-ant-your-anthropic-key" | oasis rofl secret set ANTHROPIC_API_KEY - -echo -n "xai-your-xai-key" | oasis rofl secret set XAI_API_KEY - - -# 5. Build -oasis rofl build - -# 6. Update on-chain config -oasis rofl update - -# 7. Push -oasis rofl push - -# 8. Deploy -oasis rofl deploy - -# 9. Get your endpoints -oasis rofl machine show -``` - -## Your Endpoints - -After `oasis rofl machine show`, you'll see: - -``` -Proxy: - Domain: m1234.test-proxy-b.rofl.app - Ports: - 3001: https://p3001.m1234.test-proxy-b.rofl.app # Gateway API - 3000: https://p3000.m1234.test-proxy-b.rofl.app # Dashboard -``` - -## Testing - -Replace `m1234` with your actual domain from the output above. - -```bash -# Health check -curl https://p3001.m1234.test-proxy-b.rofl.app/health - -# List models -curl https://p3001.m1234.test-proxy-b.rofl.app/v1/models - -# Chat completion (OpenAI) -curl https://p3001.m1234.test-proxy-b.rofl.app/v1/chat/completions \ - -H "Content-Type: application/json" \ - -d '{ - "model": "gpt-4o-mini", - "stream": true, - "messages": [{"role": "user", "content": "Hello!"}] - }' - -# Chat completion (Anthropic) -curl https://p3001.m1234.test-proxy-b.rofl.app/v1/chat/completions \ - -H "Content-Type: application/json" \ - -d '{ - "model": "claude-sonnet-4-20250514", - "stream": true, - "messages": [{"role": "user", "content": "Hello!"}] - }' -``` - -## Use with OpenAI-Compatible Tools - -```bash -export OPENAI_BASE_URL=https://p3001.m1234.test-proxy-b.rofl.app/v1 -export OPENAI_API_KEY="not-needed" # Keys are in TEE -``` - -## Useful Commands - -| Command | Description | -|---------|-------------| -| `oasis rofl show` | View app status | -| `oasis rofl machine show` | View endpoints and machine info | -| `oasis rofl machine logs` | View logs | -| `oasis rofl secret list` | List secrets | - -## Troubleshooting - -**"app identifier already defined"**: Remove `deployments` section from `rofl.yaml` and run `oasis rofl create` again. - -**"forbidden"**: You're using a different wallet than the one that created the app. Check with `oasis wallet list`. - -**Build failures**: Ensure Docker is running (`docker ps`) and you have disk space (`df -h`). - -**Insufficient funds**: Get testnet tokens from https://faucet.testnet.oasis.io/ - -## Resources - -- [Oasis ROFL Docs](https://docs.oasis.io/rofl/) -- [Oasis CLI Reference](https://cli.oasis.io) -- [Testnet Faucet](https://faucet.testnet.oasis.io/) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index eb4767d..9377723 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,12 +1,11 @@ # Table of contents -* [Ekai Documentation](intro.md) +* [Contexto Documentation](intro.md) * [Architecture Overview](architecture-overview.md) * [Getting Started](getting-started.md) +* [Contexto Plugin](contexto.md) * [Memory](memory-plugin.md) -* [OpenRouter Quickstart](openrouter-quickstart.md) +* [Supported Providers and Models](providers-and-models.md) +* [OpenRouter Integration Quickstart](openrouter-quickstart.md) * [Usage with Claude Code](USAGE_WITH_CLAUDE_CODE.md) * [Usage with Codex](USAGE_WITH_CODEX.md) -* [Get Started with x402](GET_STARTED_WITH_X402.md) -* [Supported Providers and Models](providers-and-models.md) -* [ROFL Deployment](ROFL_DEPLOYMENT.md) diff --git a/docs/images/architecture-x402.png b/docs/images/architecture-x402.png deleted file mode 100644 index 8d69b5a..0000000 Binary files a/docs/images/architecture-x402.png and /dev/null differ diff --git a/docs/images/architecture.png b/docs/images/architecture.png deleted file mode 100644 index 993cbf0..0000000 Binary files a/docs/images/architecture.png and /dev/null differ diff --git a/docs/images/x402-flow.jpeg b/docs/images/x402-flow.jpeg deleted file mode 100644 index 0141aef..0000000 Binary files a/docs/images/x402-flow.jpeg and /dev/null differ diff --git a/docs/memory-plugin.md b/docs/memory-plugin.md index c849819..dc77796 100644 --- a/docs/memory-plugin.md +++ b/docs/memory-plugin.md @@ -1,19 +1,8 @@ # Memory -Agent-centric, local-first semantic memory. Your agent reflects on conversations and decides what to learn — memory is first-person, not a passive database about users. +Agent-centric, local-first semantic memory. Your agent reflects on conversations and decides what to learn -- memory is first-person, not a passive database about users. -## Two Ways to Use - -| Path | Best for | -|------|----------| -| **SDK / HTTP API** | Embedding memory into your own Node/TS app or service | -| **OpenClaw Plugin** | Drop-in memory for OpenClaw agents (zero code) | - -Both use the same `@ekai/memory` engine underneath. - ---- - -## Way 1: SDK / HTTP API +## SDK / HTTP API ### Install @@ -87,80 +76,7 @@ npm run start -w @ekai/memory | GET | `/v1/graph/triples` | Query semantic triples | | GET | `/v1/graph/visualization` | Graph visualization data | -All endpoints accept an `agent` query/body param. Full API reference: [`memory/README.md`](../memory/README.md). - ---- - -## Way 2: OpenClaw Plugin (@ekai/contexto) - -### Install - -```bash -openclaw plugins install @ekai/contexto -``` - -Or from source: - -```bash -openclaw plugins install ./integrations/openclaw -``` - -### Configure - -In your OpenClaw config: - -```json5 -{ - plugins: { - allow: ["@ekai/contexto"], - entries: { - "@ekai/contexto": { - enabled: true, - config: { - "dbPath": "~/.openclaw/ekai/memory.db", - "provider": "openai", - "apiKey": "sk-..." - } - } - } - } -} -``` - -### How It Works - -Two lifecycle hooks plus one slash command — no code required: - -1. **`agent_end`** — After each conversation turn, new messages are normalized, redacted (secrets stripped), and ingested into memory. - -2. **`before_prompt_build`** — Before the agent responds, the last user message is used to search memory. Up to 5 relevant memories are prepended as context (capped at 2000 chars). - -3. **`/memory-bootstrap`** — Manually backfills existing OpenClaw session JSONL transcripts into memory. Runs in the background and logs progress. - -Delta tracking is persisted to `{dbPath}.progress.json` so only new messages are ingested, even across restarts. - -### Bootstrap Existing History - -If installing on an existing OpenClaw instance, backfill historical sessions: - -``` -/memory-bootstrap -``` - -The command is auth-gated, returns immediately, and runs in the background. If bootstrap is already running or completed, it returns a no-op status message. - -Bootstrap scans `{stateDir}/agents/*/sessions/*.jsonl`, skips `.reset.` files, and skips malformed JSON lines with warnings. - -Progress is tracked in `{dbPath}.progress.json`, so bootstrap resumes if interrupted. - -Note: `agent_end` ingests with `userId` scoping when available, while bootstrap currently ingests historical sessions without `userId`. - -### Verify - -```bash -openclaw plugins list # should show @ekai/contexto -openclaw hooks list # should show plugin:@ekai/contexto:* hooks -``` +All endpoints accept an `agent` query/body param. Full API reference: [`packages/memory/README.md`](../packages/memory/README.md). --- @@ -189,15 +105,6 @@ openclaw hooks list # should show plugin:@ekai/contexto:* hooks | `MEMORY_PORT` | `4005` | Standalone server port | | `MEMORY_CORS_ORIGIN` | `*` | CORS origins (standalone mode) | -### Plugin Config (@ekai/contexto) - -| Setting | Default | Description | -|---------|---------|-------------| -| `dbPath` | `~/.openclaw/ekai/memory.db` | Path to SQLite memory file | -| `provider` | env-based | LLM provider (`openai`, `gemini`, `openrouter`) | -| `apiKey` | env-based | API key for the selected provider | -| `bootstrapDelayMs` | `1000` | Delay between sessions during `/memory-bootstrap` | - ### Supported Providers | Provider | Embed Model (default) | Extract Model (default) | @@ -229,4 +136,4 @@ Semantic triples are tagged with a domain — `user`, `world`, or `self`. User-d --- -For the full data model, retrieval pipeline, and consolidation details, see [`memory/README.md`](../memory/README.md). For plugin development, see [`integrations/openclaw/README.md`](../integrations/openclaw/README.md). +For the full data model, retrieval pipeline, and consolidation details, see [`packages/memory/README.md`](../packages/memory/README.md).