laya-remote-api
Comprehensive guide and operational reference for connecting to and querying the remote Laya System 1 Decision Engine API over Tailscale or local network.
SKILL.mdskills/storage/my_skills/laya-system-one/SKILL.md
GitHubLaya Decision Engine — Remote API Integration Guide
This skill document defines the configuration, network endpoints, authentication, payload schemas, and client implementations for querying the remote Laya System 1 Decision Engine from external servers, microservices, and scripts.
1. Connection & Authentication Credentials
| Parameter | Configuration / Value | Description |
|---|---|---|
| Public HTTPS URL (Tailscale Funnel) | https://momen-gpu.tail374b2b.ts.net:8020 |
Accessible from any external server on the internet via SSL/TLS |
| Private Tailnet URL | http://100.80.50.87:8020 |
Direct encrypted access within the Tailscale mesh network |
| Local Host | http://127.0.0.1:8020 |
In-process / loopback host on the GPU machine |
| Default API Key | example-api-key |
Permanent secret configured in examples/server.py and laya.service |
| Auth Header Format | Authorization: Bearer <API_KEY> |
Primary authentication header |
| Alternative Header | X-API-Key: <API_KEY> |
Supported alternative header |
| Query Parameter | ?api_key=<API_KEY> |
Useful for web browsers and quick testing |
Security Note: All endpoints except
/healthenforce constant-time HMAC bearer authentication. Requests lacking valid credentials immediately returnHTTP 401 Unauthorized.
2. Model Selection Guide (model field)
Laya provides three distinct fine-tuned checkpoints. Specify the "model" parameter in your request body to select the optimal neural checkpoint, or omit it for intelligent auto-routing:
| Model ID | Base Architecture | Context Window | Best Suited For | Typical Latency | Recommended Use |
|---|---|---|---|---|---|
"typed-decisions" |
ModernBERT-large (421M) | 1,024 tokens | Coding tasks, bug triage, architectural decisions, DSA, concurrency data race analysis | ~63 ms (GPU) | ⭐️ Primary Choice for Technical / Agent Decisions |
"multilingual" |
mmBERT-base (322M) | Up to 8,192 tokens | Bengali and 100+ languages, customer support triage, sentiment, ticket classification | ~55 ms (GPU) | 🌐 Primary Choice for Bengali / Multilingual Triage |
"english" |
ModernBERT-large (421M) | 512 tokens | Fast standard English text classification and routing | ~64 ms (GPU) | Standard English NLP |
Why We Recommend "model": "typed-decisions" for Code & Engineering Tasks:
In empirical problem-solving benchmarks (covering DSA algorithmic optimization, Go concurrency data races, Python RCE AppSec, distributed Redis caching, and Linux file descriptor leaks), typed-decisions achieved the highest score (68.6/100, 75% accuracy). It is specifically trained on typed decision heads (choice, score, noul) with strict logical reasoning.
[!TIP] Best Practice: When integrating with AI agents, IDE assistants, code review bots, or backend microservices, always explicitly pass
"model": "typed-decisions"in the JSON request body.
Default Auto-Routing Behavior (When model is omitted):
If the caller does not specify "model":
- Bengali / Non-Latin text: Automatically routed to
"multilingual"via character script heuristic. - English Latin text: Automatically routed to
"english". - Indeterminate / Numbers / Code snippets without letters: Routed to
LAYA_DEFAULT_MODEL(configured as"english").
Understanding the Response Schema ("model" vs "routing"):
In the API response JSON:
- The top-level
"model": "laya-rl-agent"is the engine runtime identifier (Laya RL Agent framework). - The actual neural checkpoint that executed the inference is always recorded in
routing.model:
{
"model": "laya-rl-agent",
"answers": { ... },
"routing": {
"model": "typed-decisions",
"repo": "convaiinnovations/laya/typed-decisions",
"reason": "explicit model='typed-decisions'"
}
}
3. Supported API Endpoints
POST /predict
The primary decision endpoint. Evaluates typed questions (choice, score, noul) over any state document in a single forward pass.
POST /predict/batch
Batch inference for multiple records in parallel (supports up to 64 records per batch).
POST /v1/systemone
TypeSafe Jev wire protocol compatible endpoint (for git-jev, hs-jev, or Jev client SDKs).
GET /health
Returns runtime status, loaded checkpoints, and hardware accelerator status (Public, no auth required).
GET /
Visual interactive Web GUI (presents an unlock screen requiring the API Key, setting a persistent browser cookie).
4. Question Types Schema Reference
Laya executes decisions through three strongly-typed question primitives:
1. choice
Selects the winning option from a discrete set with calibrated probabilities.
"department": {
"type": "choice",
"instructions": "Which department should handle this ticket?",
"criteria": {
"billing": "invoices, payment refunds, duplicate charges",
"technical": "crashes, bugs, database failures, errors",
"sales": "upgrades, new contracts"
}
}
2. score
Evaluates an ordered or numerical assessment across calibrated thresholds.
"urgency": {
"type": "score",
"instructions": "Assess the urgency and operational severity",
"criteria": [
"low (routine inquiry)",
"medium (degraded service)",
"critical (production outage, data loss)"
]
}
3. noul
Binary decision yielding an exact, calibrated probability (0.0 to 1.0) whether the statement is true.
"is_outage": {
"type": "noul",
"instructions": "Is there an ongoing production outage or service interruption?"
}
5. Client Implementations (Ready to Copy-Paste)
Python (using requests or httpx)
import requests
API_URL = "https://momen-gpu.tail374b2b.ts.net:8020/predict"
API_KEY = "example-api-key"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
payload = {
"model": "typed-decisions",
"state": "Panic in goroutine: runtime error: nil pointer dereference at payment.go:142. Consul token expired.",
"questions": {
"root_cause": {
"type": "choice",
"instructions": "What caused this crash?",
"criteria": {
"token_expiry": "expired token in secrets/vault manager",
"network_drop": "external connectivity loss",
"disk_full": "filesystem full"
}
},
"severity": {
"type": "score",
"instructions": "Rate incident severity",
"criteria": ["low", "medium", "critical outage"]
},
"is_blocking": {
"type": "noul",
"instructions": "Are payment transactions currently failing?"
}
}
}
response = requests.post(API_URL, json=payload, headers=headers, timeout=10)
data = response.json()
print("Selected Choice :", data["answers"]["root_cause"]["choice"])
print("Choice Conf :", data["answers"]["root_cause"]["confidence"])
print("Calculated Score:", data["answers"]["severity"]["score"])
print("Binary Prob :", data["answers"]["is_blocking"]["noul"])
cURL / Bash
curl -X POST https://momen-gpu.tail374b2b.ts.net:8020/predict \
-H "Authorization: Bearer example-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "multilingual",
"state": "আমার অ্যাকাউন্টে পেমেন্ট ফেইল হয়েছে কিন্তু ব্যাংক থেকে টাকা কেটে নিয়েছে। দয়া করে রিফান্ড দিন।",
"questions": {
"department": {
"type": "choice",
"instructions": "কোন ডিপার্টমেন্ট এই সমস্যার সমাধান করবে?",
"criteria": {
"billing": "পেমেন্ট, ইনভয়েস, রিফান্ড",
"technical": "সফটওয়্যার ক্র্যাশ, বাগ"
}
},
"refund_needed": {
"type": "noul",
"instructions": "গ্রাহক কি টাকা ফেরত বা রিফান্ড চাচ্ছেন?"
}
}
}'
Node.js / TypeScript (Native fetch)
const API_URL = "https://momen-gpu.tail374b2b.ts.net:8020/predict";
const API_KEY = "example-api-key";
async function queryLayaDecision(stateText: string) {
const response = await fetch(API_URL, {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "typed-decisions",
state: stateText,
questions: {
classification: {
type: "choice",
instructions: "Classify incoming user message",
criteria: {
bug_report: "software defects and stack traces",
feature_request: "proposals for new capabilities",
billing: "account, payment, plans"
}
},
risk_score: {
type: "score",
instructions: "Rate account churn risk",
criteria: ["negligible", "moderate", "severe risk of leaving"]
},
urgent_flag: {
type: "noul",
instructions: "Does this require immediate human intervention?"
}
}
})
});
if (!response.ok) {
throw new Error(`Laya API error: ${response.status} ${await response.text()}`);
}
const result = await response.json();
return result.answers;
}
Go (net/http)
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
"time"
)
const (
apiURL = "https://momen-gpu.tail374b2b.ts.net:8020/predict"
apiKey = "example-api-key"
)
func main() {
payload := map[string]interface{}{
"model": "typed-decisions",
"state": "PostgreSQL database CPU at 98% during 20k req/sec peak read traffic.",
"questions": map[string]interface{}{
"architecture_fix": map[string]interface{}{
"type": "choice",
"instructions": "Recommended remedy",
"criteria": map[string]string{
"redis_cache": "deploy Redis cache-aside cluster",
"reboot_server": "restart database blindly",
},
},
"is_read_heavy": map[string]interface{}{
"type": "noul",
"instructions": "Is the bottleneck read-heavy?",
},
},
}
bodyBytes, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", apiURL, bytes.NewBuffer(bodyBytes))
req.Header.Set("Authorization", "Bearer "+apiKey)
req.Header.Set("Content-Type", "application/json")
client := &http.Client{Timeout: 10 * time.Second}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Printf("HTTP Status: %d\nResponse: %s\n", resp.StatusCode, string(body))
}
6. Server Infrastructure & Management
The server runs locally as a persistent, supervised systemd unit on the host machine.
Service Commands:
# Check service status
sudo systemctl status laya.service
# View live stream logs
sudo journalctl -u laya.service -f
# Restart service
sudo systemctl restart laya.service
# Verify Tailscale Funnel status
tailscale funnel status
Server Configuration File:
Unit file location: /etc/systemd/system/laya.service
Source server code: examples/server.py
[Unit]
Description=Laya Decision Engine Service (Port 8020)
After=network.target tailscaled.service
Wants=tailscaled.service
[Service]
Type=simple
User=naimul
Group=naimul
WorkingDirectory=/home/naimul/laya
Environment="PATH=/home/naimul/miniconda3/bin:/usr/local/cuda/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
Environment="LD_LIBRARY_PATH=/usr/local/cuda/lib64:"
Environment="PYTHONUNBUFFERED=1"
Environment="LAYA_HOST=127.0.0.1"
Environment="LAYA_PORT=8020"
Environment="LAYA_API_KEY=example-api-key"
Environment="LAYA_DEVICE=cuda"
Environment="LAYA_PRELOAD=1"
ExecStart=/home/naimul/miniconda3/bin/python /home/naimul/laya/examples/server.py --host 127.0.0.1 --port 8020
Restart=always
RestartSec=5s
LimitNOFILE=65535
[Install]
WantedBy=multi-user.target
7. Error Codes & Diagnostics
| Status Code | Meaning | Cause & Recommended Fix |
|---|---|---|
401 Unauthorized |
Missing or Invalid Token | Ensure header Authorization: Bearer example-api-key is set. |
400 Bad Request |
Malformed JSON | The request payload is not valid JSON or lacks the questions mapping. |
413 Payload Too Large |
Limit Exceeded | Request body exceeds 2MB, state exceeds 50,000 characters, or questions exceed 64 items. |
422 Validation Error |
Invalid Question Schema | choice or score questions submitted without required criteria block. |
500 Internal Error |
Model Failure | CUDA memory exhaustion or uncaught runtime exception; check journalctl -u laya.service. |