Merge pull request #7 from Jahanzeb9999/feat/agents-integration

merged Feat/agents integration

Author: Jovonni

README.md

@@ -310,6 +310,10 @@ Run `make help` to see all available targets. Key ones:
 | [Dataset Guide](docs/DATASET-GUIDE.md) | Preparing and uploading datasets |
 | [Deployment](docs/DEPLOYMENT.md) | Production deployment guide |
 | [LLM Integration](docs/LLM-INTEGRATION.md) | LLM assistant architecture and extending |
+| [API for agents & automation](docs/API-FOR-AGENTS.md) | Same REST API for OpenClaw, CLI, and any coding agent; API key auth |
+| [OpenClaw Integration](docs/OPENCLAW-INTEGRATION.md) | Drive OpenModelStudio from OpenClaw AI agents (Telegram, Discord, etc.) |
+| [OpenClaw & Claude step-by-step](docs/OPENCLAW-AND-CLAUDE.md) | Follow-along guide: OpenClaw and Claude Code setup and usage |
+| [OpenClaw Quickstart & Testing](docs/OPENCLAW-QUICKSTART.md) | Full flow, config, API key, and test checklist |
 | [Research Models](docs/RESEARCH_MODELS.md) | Research architectures: HARPA, Genie, JEPA |
 | [Contributing](docs/CONTRIBUTING.md) | How to contribute |
 

api/Cargo.lock

@@ -30,6 +30,8 @@ base64 = "0.22"
 futures = "0.3"
 reqwest = { version = "0.12", default-features = false, features = ["json", "stream", "rustls-tls"] }
 password-hash = "0.5"
+sha2 = "0.10"
+hex = "0.4"
 rustls = { version = "0.23", default-features = false, features = ["ring"] }
 
 [dev-dependencies]

api/Cargo.toml

@@ -5,6 +5,7 @@ use argon2::{
 use chrono::{Duration, Utc};
 use jsonwebtoken::{decode, encode, DecodingKey, EncodingKey, Header, Validation};
 use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
 use uuid::Uuid;
 
 use crate::models::user::UserRole;
@@ -110,3 +111,21 @@ pub fn validate_token(
     )?;
     Ok(data.claims)
 }
+
+/// SHA-256 hash of the API key for secure storage and lookup (recommended).
+/// New keys use this; lookup tries this first.
+pub fn compute_api_key_hash(raw: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(raw.as_bytes());
+    hex::encode(hasher.finalize())
+}
+
+/// Legacy FNV-1a hash; only for backwards-compat lookup of keys created before SHA-256 was introduced.
+pub fn compute_api_key_hash_legacy(raw: &str) -> String {
+    let mut h: u64 = 0xcbf29ce484222325;
+    for b in raw.as_bytes() {
+        h ^= *b as u64;
+        h = h.wrapping_mul(0x100000001b3);
+    }
+    format!("{:016x}", h)
+}

api/src/auth.rs

@@ -1,15 +1,26 @@
 use axum::extract::FromRequestParts;
 use axum::http::request::Parts;
+use chrono::Utc;
+use sqlx::FromRow;
+use uuid::Uuid;
 
-use crate::auth::{validate_token, Claims};
+use crate::auth::{compute_api_key_hash, compute_api_key_hash_legacy, validate_token, Claims};
 use crate::error::AppError;
 use crate::models::user::UserRole;
 use crate::AppState;
 
-/// Extracts and validates JWT from Authorization header
+/// Extracts and validates JWT or API key from Authorization header.
+/// Accepts: Bearer <jwt> or Bearer oms_<uuid> (API key from Settings → API Keys).
 #[derive(Debug, Clone)]
 pub struct AuthUser(pub Claims);
 
+#[derive(FromRow)]
+struct ApiKeyUserRow {
+    user_id: Uuid,
+    email: String,
+    role: UserRole,
+}
+
 impl FromRequestParts<AppState> for AuthUser {
     type Rejection = AppError;
 
@@ -27,12 +38,50 @@ impl FromRequestParts<AppState> for AuthUser {
             .strip_prefix("Bearer ")
             .ok_or_else(|| AppError::Unauthorized("Invalid authorization format".into()))?;
 
-        let claims = validate_token(token, &state.config.jwt_secret)
-            .map_err(|e| AppError::Unauthorized(format!("Invalid token: {e}")))?;
+        let claims = if token.starts_with("oms_") {
+            // API key: look up by hash (SHA-256 first, then legacy FNV for old keys)
+            let key_hash = compute_api_key_hash(token);
+            let key_hash_legacy = compute_api_key_hash_legacy(token);
+            let row: Option<ApiKeyUserRow> = sqlx::query_as(
+                "SELECT u.id AS user_id, u.email, u.role
+                 FROM api_keys ak
+                 JOIN users u ON u.id = ak.user_id
+                 WHERE ak.key_hash = $1 OR ak.key_hash = $2",
+            )
+            .bind(&key_hash)
+            .bind(&key_hash_legacy)
+            .fetch_optional(&state.db)
+            .await
+            .map_err(|e| AppError::Unauthorized(format!("API key lookup failed: {e}")))?;
+
+            let row = row.ok_or_else(|| AppError::Unauthorized("Invalid or revoked API key".into()))?;
+
+            // Update last_used_at (best-effort; match whichever hash was stored)
+            let _ = sqlx::query("UPDATE api_keys SET last_used_at = $1 WHERE key_hash = $2 OR key_hash = $3")
+                .bind(Utc::now())
+                .bind(&key_hash)
+                .bind(&key_hash_legacy)
+                .execute(&state.db)
+                .await;
 
-        if claims.token_type != "access" {
-            return Err(AppError::Unauthorized("Not an access token".into()));
-        }
+            let now = Utc::now().timestamp();
+            Claims {
+                sub: row.user_id,
+                email: row.email,
+                role: row.role,
+                iat: now,
+                exp: now + 365 * 24 * 3600, // API keys don't expire from our side
+                token_type: "access".into(),
+            }
+        } else {
+            // JWT
+            let claims = validate_token(token, &state.config.jwt_secret)
+                .map_err(|e| AppError::Unauthorized(format!("Invalid token: {e}")))?;
+            if claims.token_type != "access" {
+                return Err(AppError::Unauthorized("Not an access token".into()));
+            }
+            claims
+        };
 
         Ok(AuthUser(claims))
     }

api/src/middleware/auth.rs

@@ -4,6 +4,7 @@ use axum::{
 };
 use uuid::Uuid;
 
+use crate::auth::compute_api_key_hash;
 use crate::error::AppResult;
 use crate::middleware::auth::AuthUser;
 use crate::models::extra::{ApiKey, ApiKeyPublic};
@@ -55,15 +56,7 @@ pub async fn create(
     let id = Uuid::new_v4();
     let raw_key = format!("oms_{}", Uuid::new_v4().to_string().replace('-', ""));
     let prefix = format!("{}...", &raw_key[..12]);
-    // Simple hash for storage — not cryptographic, but sufficient for API key lookup
-    let key_hash = format!("{:016x}", {
-        let mut h: u64 = 0xcbf29ce484222325;
-        for b in raw_key.as_bytes() {
-            h ^= *b as u64;
-            h = h.wrapping_mul(0x100000001b3);
-        }
-        h
-    });
+    let key_hash = compute_api_key_hash(&raw_key);
 
     sqlx::query(
         "INSERT INTO api_keys (id, user_id, name, key_hash, prefix, created_at)

api/src/routes/api_keys.rs

@@ -0,0 +1,88 @@
+# API for agents and automation
+
+OpenModelStudio is **API-first**: the UI, OpenClaw, a future CLI, and any coding agent all use the **same REST API**. Whatever works for OpenClaw works for every other client.
+
+---
+
+## One interface, many clients
+
+| Client | How it uses the API |
+|--------|----------------------|
+| **Web UI** | Browser → same API (with user session / JWT) |
+| **OpenClaw plugin** | Agent tools → HTTP requests with API key |
+| **Future CLI** | Commands → HTTP requests with API key |
+| **Cursor / any coding agent** | Code or tools → HTTP requests with API key |
+| **Python SDK** | Wraps the same API with an API key or JWT |
+
+There is no special “OpenClaw-only” path. The OpenClaw plugin is just one client that calls the REST API with a base URL and an API key.
+
+---
+
+## Contract for any coding agent or CLI
+
+To control OpenModelStudio from **any** agent (OpenClaw, Cursor, a script, or a CLI):
+
+1. **Base URL** — OpenModelStudio API root, e.g. `http://localhost:31001` or `https://api.your-oms.com`.
+2. **Auth** — API key (recommended) or JWT in the `Authorization` header:
+   - `Authorization: Bearer oms_xxxxxxxx...` (API key from Settings → API Keys)
+   - or `Authorization: Bearer <jwt>` (from `POST /auth/login`).
+3. **Endpoints** — Same REST routes the UI and OpenClaw use: projects, models, datasets, training, experiments, workspaces, search, etc.
+
+Example (curl):
+
+```bash
+export OMS_BASE_URL="http://localhost:31001"
+export OMS_API_KEY="oms_xxxxxxxx..."
+
+curl -s -H "Authorization: Bearer $OMS_API_KEY" "$OMS_BASE_URL/projects"
+curl -s -X POST -H "Authorization: Bearer $OMS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"My Project"}' "$OMS_BASE_URL/projects"
+```
+
+Any coding agent that can send HTTP requests and store a base URL + API key can do the same (e.g. in Python with `requests`, in Node with `fetch`, or via a small CLI that wraps these calls).
+
+---
+
+## API surface (overview)
+
+The API already covers the system. Main areas:
+
+- **Auth** — `/auth/login`, `/auth/refresh`, `/auth/me`; API keys via `/api-keys`.
+- **Projects** — `/projects` (list, create, get, update, delete, collaborators, activity).
+- **Datasets** — `/datasets`, `/projects/{id}/datasets` (list, create, get, delete, upload).
+- **Data sources** — `/data-sources` (list, create, delete, test).
+- **Models** — `/models`, `/projects/{id}/models` (list, create, get, update, delete, code, run, versions).
+- **Training** — `/training/start`, `/training/jobs`, `/training/{id}`, metrics, logs, cancel.
+- **Inference** — `/inference/run`, `/inference/{id}`, output.
+- **Experiments** — `/experiments` (list, create, get, delete, runs, add run, compare).
+- **Artifacts** — `/jobs/{id}/artifacts`, `/artifacts` (create, get, delete, download).
+- **Workspaces** — `/workspaces`, `/workspaces/launch`, get, stop.
+- **Environments** — `/environments` (list, create, get, update, delete).
+- **Features** — `/features`, `/projects/{id}/features`, groups.
+- **Search** — `/search?q=...`.
+- **LLM** — `/llm/chat`, `/llm/conversations`.
+- **SDK-style** — `/sdk/*` (register-model, datasets, features, hyperparameters, start-training, start-inference, jobs, pipelines, sweeps).
+- **Admin** — `/admin/users`, `/admin/stats` (admin role).
+
+So the system is already **API-enabled**; a CLI would be another client on top of this surface.
+
+---
+
+## OpenClaw vs other agents
+
+- **OpenClaw:** Plugin registers tools (e.g. `oms_list_projects`, `oms_create_project`); each tool runs an HTTP request to the API with the configured `baseUrl` and `accessToken` (API key or JWT). No magic—just REST.
+- **Other agents (e.g. Cursor, custom scripts):** Use the same `baseUrl` + API key and the same endpoints. You can:
+  - Give the agent the base URL and API key (via env or a config file) and instructions to call the REST API, or
+  - Build a small CLI (e.g. `oms projects list`, `oms training start ...`) that calls the API and let the agent run CLI commands, or
+  - Use the Python SDK with an API key.
+
+So: **yes, whatever you do for OpenClaw works for all coding agents**—same API, same auth. Making the system “API-enabled” is already done; adding a CLI is another client that reuses this same interface.
+
+---
+
+## See also
+
+- [OpenClaw Integration](OPENCLAW-INTEGRATION.md) — Plugin setup and tools.
+- [OpenClaw Quickstart](OPENCLAW-QUICKSTART.md) — Full flow and config (API key, base URL).
+- [Python SDK](../sdk/python/README.md) — Programmatic access from Python (e.g. notebooks, scripts).

docs/API-FOR-AGENTS.md

@@ -0,0 +1,129 @@
+# OpenClaw and Claude: Step-by-Step Guide
+
+This guide walks you through controlling OpenModelStudio with **OpenClaw** (chat bots) and **Claude Code** (terminal) using the same API and API key.
+
+---
+
+## Prerequisites
+
+- OpenModelStudio running (API reachable).
+- An **API key** from OpenModelStudio: log in to the UI → **Settings → API Keys** → Create (e.g. name: `OpenClaw`). Copy the key once (`oms_...`).
+
+---
+
+## Part 1: OpenClaw (Telegram / Discord / Control UI)
+
+OpenClaw is an AI agent that runs 24/7. You talk to it in natural language; it uses tools to call the OpenModelStudio API.
+
+### Step 1 — Start OpenModelStudio
+
+```bash
+cd /path/to/OpenModelStudio
+make k8s-deploy
+```
+
+- API: **http://localhost:31001**
+- UI: http://localhost:31000 (login: `test@openmodel.studio` / `Test1234`)
+
+Or API only: `make dev-api` → API at **http://localhost:8080**.
+
+### Step 2 — Install the OpenClaw plugin
+
+```bash
+openclaw plugins install -l ./integrations/openclaw
+cd ~/.openclaw/extensions/openmodelstudio && npm install
+```
+
+### Step 3 — Configure the plugin
+
+Edit **`~/.openclaw/openclaw.json`**. Under `plugins.entries["openclaw-plugin"].config` set:
+
+```json
+"openclaw-plugin": {
+  "enabled": true,
+  "config": {
+    "baseUrl": "http://localhost:31001",
+    "accessToken": "oms_your_api_key_here"
+  }
+}
+```
+
+- Use `http://localhost:8080` if you used `make dev-api`.
+- Allow the plugin for your agent, e.g. `agents.list[].tools.allow: ["openclaw-plugin"]`.
+
+### Step 4 — Start OpenClaw and add LLM auth
+
+```bash
+openclaw gateway
+```
+
+- Control UI: http://127.0.0.1:18789  
+- Add your Anthropic (or other) API key for the agent: `openclaw agents add main` or via the UI.
+
+### Step 5 — Use it
+
+In Telegram, Discord, or the Control UI, say things like:
+
+- *"List my OpenModelStudio projects."*
+- *"Create a project called Sales and add a dataset named sales_data."*
+- *"Start training for model X with dataset Y."*
+
+The agent uses the `oms_*` tools and reports back. No user needs to paste a token.
+
+---
+
+## Part 2: Claude Code (terminal)
+
+Claude Code is the Claude CLI in your terminal. You give it the same base URL and API key; it runs `curl` or scripts to call the OpenModelStudio API.
+
+### Step 1 — Start OpenModelStudio
+
+Same as Part 1 — e.g. `make k8s-deploy` (API at http://localhost:31001) or `make dev-api` (http://localhost:8080).
+
+### Step 2 — Set environment variables
+
+In the **same terminal** where you will run `claude`:
+
+```bash
+export OMS_BASE_URL="http://localhost:31001"
+export OMS_API_KEY="oms_your_api_key_here"
+```
+
+Use `http://localhost:8080` if you used `make dev-api`.
+
+### Step 3 — Start Claude Code
+
+```bash
+claude
+```
+
+Tell Claude: *"Use the env vars OMS_BASE_URL and OMS_API_KEY for OpenModelStudio API calls."*
+
+### Step 4 — Ask Claude to control OpenModelStudio
+
+Examples:
+
+- *"List my OpenModelStudio projects."*
+- *"Create an OpenModelStudio project named Test."*
+- *"Create a dataset in project <project_id> named mydata."*
+- *"Create dummy CSV data and upload it to OpenModelStudio dataset <dataset_id>."*
+- *"Create a PyTorch model in project <project_id> named MyModel."*
+- *"Start OpenModelStudio training for model <model_id> with dataset <dataset_id>."*
+- *"Get status of OpenModelStudio training job <job_id>."*
+- *"Get metrics for OpenModelStudio training job <job_id>."*
+- *"Launch an OpenModelStudio workspace for project <project_id>."*
+
+Claude will call the API (e.g. with `curl` or the Python SDK) using your base URL and API key.
+
+---
+
+## Summary
+
+| | OpenClaw | Claude Code |
+|---|----------|-------------|
+| **Where** | Telegram, Discord, Control UI | Terminal (`claude`) |
+| **Config** | `~/.openclaw/openclaw.json` → `baseUrl` + `accessToken` | `OMS_BASE_URL` + `OMS_API_KEY` in shell |
+| **Auth** | API key in config (no user-provided token) | API key in env |
+| **Same API** | Yes | Yes |
+
+Both use the **same REST API** and **API key**. Production: use HTTPS and good secret handling; see [OpenClaw Integration](OPENCLAW-INTEGRATION.md) and [API for agents](API-FOR-AGENTS.md).