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.md

GitHub

Laya 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 /health enforce constant-time HMAC bearer authentication. Requests lacking valid credentials immediately return HTTP 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.