💡 What is TERMES?

TERMES is the autonomous web digesting, headless automation, and synthetic API engine of the Terra Ecosystem (inspired by termite mound biology and symbiotic digestion).

It allows developers to turn ANY website without an API, e-commerce store, legacy portal, SPA, or document into a live Inverted API and Site-to-Webhook event trigger with 100% Privacy & Security and $0 Monthly Server Overhead.

[!IMPORTANT] No Git Cloning Needed! The core Terra monorepo is private. TERMES is distributed globally over the internet as an open-access NPM package (terra-termes) and live Web Console. You do NOT need to clone any repository to use TERMES in your terminal or applications.

⚡ How TERMES Works (The Inverted API Concept)

In traditional web development, APIs are published and controlled by target service providers (who often paywall or restrict them).

TERMES Inverted APIs invert this relationship:

                            🏰 TERMES CONSOLE / TERMITARIUM
                                   (Control Plane)
                                          │
                ┌─────────────────────────┼─────────────────────────┐
                ▼                         ▼                         ▼
        👃 NASUTE WORKERS        🕳️ MUD TUNNEL PROXY        🪵 CELLULOSE PROCESSOR
      (Headless Execution)      (Stealth & Anti-Bot)          (HTML/DOM Cleaning)
                │                         │                         │
                └─────────────────────────┼─────────────────────────┘
                                          ▼
                               🦠 PROTOZOA ENGINE
                      (Parser CSS/XPath & Schema Builder)
                                          │
                ┌─────────────────────────┴─────────────────────────┐
                ▼                                                   ▼
       🌐 SYNTHETIC REST API                                 🦟 ALATES SWARM
     (Termitomyces - 0ms CDN)                             (Inverted Webhooks Engine)
                │                                                   │
                └─────────────────────────┬─────────────────────────┘
                                          ▼
                                 🔄 TROPHALLAXIS
          (Feeds to Combase/Rolla & AWS/Azure/GCP Multi-Cloud Bridges)

1. Declare Spec (Termitarium 🏰): Define CSS selectors, XPath rules, or regex patterns for the target data you want to extract from any website in the world.
2. Stealth Navigation (Mud Tunnel 🕳️ & Nasute Workers 👃): TERMES navigates target sites using headless runners with anti-bot bypass, stealth headers, and proxy rotation.
3. Digest Raw Content (Cellulose Processor 🪵 & Protozoa Engine 🦠): Cleans raw HTML/DOM trees and digests unstructured cellulose into clean JSON schemas.
4. Publish Synthetic REST API (Termitomyces 🍄): Cultivates and publishes live Synthetic REST APIs on global CDN (GitHub Pages / Raw CDN) with 0ms server delay and $0 cost.
5. Site-to-Webhook (Alates Swarm 🦟): Converts passive websites into active Inverted Webhooks. TERMES monitors DOM content changes and dispatches instant POST alerts to your app, Discord, or Slack.
6. Multi-Cloud Data Feeds (Trophallaxis 🔄): Streams digested data directly to Terra Titans (Combase, Rolla, Lumina) and Cloud Providers (AWS S3, Azure Blob, GCP Storage).

🏛️ Ecosystem Core Concepts & Terminology

| Biological Metaphor | Module Name | Technical Function | | :--- | :--- | :--- | | 🏰 Termitarium | Extraction Spec Engine | Control panel & recipe manager storing target URLs and CSS selectors. | | 👃 Nasute Workers | Headless Execution | Autonomous web runners executing extraction tasks. | | 🕳️ Mud Tunnel | Stealth Layer | User-Agent rotation, stealth proxying, and Anti-Bot bypass. | | 🪵 Cellulose | DOM Content | Unstructured raw HTML, JavaScript DOM trees, or document tables. | | 🦠 Protozoa | Symbiotic Parser | Schema builder converting raw DOM nodes into structured JSON objects. | | 🍄 Termitomyces | Synthetic APIs | Live public or private REST endpoints served from global CDNs at 0ms. | | 🦟 Alates Swarm | Inverted Webhooks | Site-to-Webhook engine firing HTTP alerts when target DOM varies. | | 🔄 Trophallaxis | Multi-Cloud Bridges | Data exchange pipelines feeding Combase, Rolla, AWS, Azure, and GCP. |

📦 Global Installation & Quick Start

Installing TERMES requires only Node.js 18+ installed on your machine.

Option 1: Global CLI Installation (Recommended)

Install terra-termes globally via NPM:

# Install globally from NPM
npm install -g terra-termes

# Verify installation
termes --version

Option 2: Instant NPX Execution (No Setup)

Run TERMES CLI directly without permanent installation:

# Launch live web console directly
npx terra-termes console

# Create an extraction spec
npx terra-termes spec list

🔑 Authentication Setup

TERMES uses a GitHub Personal Access Token (PAT) with repo permissions to publish 0ms Synthetic APIs and maintain state at $0 cost.

Set your token as an environment variable in your terminal:

# On Linux / macOS
export GITHUB_TOKEN="ghp_your_github_personal_access_token"

# On Windows PowerShell
$env:GITHUB_TOKEN="ghp_your_github_personal_access_token"

💻 CLI Commands Reference

🌐 Abrir Consola Web Local (Offline en Localhost)

# Abrir consola web local en puerto por defecto (http://localhost:3720)
termes console

# O en puerto personalizado:
termes studio --port 4000

Inicia un servidor HTTP local en http://localhost:3720 (o puerto personalizado) para administrar TERMES de forma 100% privada sin depender de Internet. Si el puerto está ocupado, detecta automáticamente el siguiente disponible.

🏰 Termitarium Extraction Specs & Inverted APIs

# 1. Create a new Inverted API Spec
termes spec create --name "tracker-precios" --url "https://tienda.com/producto" --selectors '{"precio":".price-tag","titulo":"h1"}'

# 2. List all active extraction specs
termes spec list

# 3. Digest a spec and publish live Synthetic API
termes spec digest --id spec_xyz123

# 4. Delete a spec
termes spec delete --id spec_xyz123

🦟 Alates Swarm — Inverted Webhooks (Site-to-Webhook)

# 1. Create an Inverted Webhook trigger
termes webhook create --name "Alerta Cambio Precio" --url "https://mi-app.com/webhook" --condition on_change

# 2. List active webhooks
termes webhook list

# 3. Delete a webhook
termes webhook delete --id wh_xyz123

🔄 Trophallaxis — Multi-Cloud Bridges & Mapeador de Campos

# 1. Crear un puente Multi-Cloud con Mapeador de Campos JSON
termes bridge create \
  --name "Sync Combase Events" \
  --type terra_combase \
  --repo "https://github.com/amglogicalis/combase-storage" \
  --target "sandbox_events" \
  --spec "spec_xyz123" \
  --mapper '{"precio":"price_eur","titulo":"product_title"}'

# 2. Listar puentes activos y sus destinos
termes bridge list

# 3. Probar un puente mediante Simulación Dry-Run (sin enviar datos reales)
termes bridge simulate --id bridge_xyz123

# 4. Ver histórico y logs de auditoría de un puente
termes bridge logs --id bridge_xyz123

# 5. Actualizar configuración de un puente existente
termes bridge update --id bridge_xyz123 --target "eventos_v2"

# 6. Eliminar un puente
termes bridge delete --id bridge_xyz123

🔬 Symbiont AI Gateway — Web-AI Bridge & OpenAI Endpoints (CLI & SDK)

El motor Symbiont transforma sesiones web de IA (Google Gemini Web, DeepSeek, ChatGPT, Claude) en un servidor local estándar compatible con OpenAI REST API (/v1/chat/completions) a coste $0 y sin límites de API comercial:

# 1. Iniciar el servidor local OpenAI-compatible en el puerto 7420
termes symbiont start --port 7420

# 2. Generar una llave sk-termes-symbiont con Auto-Fallback (Gemini -> DeepSeek -> ChatGPT)
termes symbiont key create --name "Cursor IDE Dev" --model "gemini-3.7-flash"

# 3. Generar una llave pública abierta (consumible sin exigencia de Bearer token)
termes symbiont key create --name "Public Dev Key" --model "gemini-3.7-flash" --no-auth

# 4. Listar todas las llaves generadas y su estado
termes symbiont key list

# 5. Registrar un proveedor web adicional o actualizar prioridad
termes symbiont provider add --type gemini_web --name "Google Gemini Web 3.7"

# 6. Listar proveedores y orden de Auto-Fallback
termes symbiont provider list

# 7. Probar una consulta de inferencia en tiempo real desde la terminal
termes symbiont test --prompt "Quien es el mejor jugador de futbol del mundo?" --model "gemini-3.7-flash"

🔌 Integración con Cursor IDE (settings.json)

{
  "openai.baseUrl": "http://localhost:7420/v1",
  "openai.apiKey": "sk-termes-symbiont-default-live",
  "openai.model": "gemini-3.7-flash"
}

🐍 Consumo desde Python con el SDK Oficial de OpenAI

from openai import OpenAI

# Conecta al Gateway de Termes en local
client = OpenAI(
    base_url="http://localhost:7420/v1",
    api_key="sk-termes-symbiont-default-live"  # o sin clave si allowPublicAccess está activo
)

response = client.chat.completions.create(
    model="gemini-3.7-flash",
    messages=[{"role": "user", "content": "Escribe un script en Python para procesar un CSV"}]
)

print(response.choices[0].message.content)

🛠️ Node.js & TypeScript SDK Usage

You can import terra-termes directly into any Node.js, Next.js, Express, or TypeScript project:

import { Termes, SymbiontGateway } from 'terra-termes';

// Initialize TERMES SDK
const termes = new Termes({
  githubToken: process.env.GITHUB_TOKEN!
});

// Load state from Vault
await termes.init();

// ── 🔬 Symbiont AI Gateway (OpenAI Compatible Bridge) [CLI / SDK Exclusive] ──
// 1. Manage Symbiont Gateway
const gateway = new SymbiontGateway();

// 2. Query Public Endpoint with Smart Auto-Wake & API Key
const response = await gateway.autoWakeAndChatCompletion(
  'ep_pub_w614r7',
  {
    model: 'gemini-3.7-flash',
    messages: [{ role: 'user', content: 'Explica la teoría de la relatividad en 1 frase' }]
  },
  'sk-termes-prod-live-99'
);

console.log('🤖 Assistant:', response.choices[0].message.content);
console.log('🔄 Provider Used:', response.provider_used);
console.log('⚠️ Fallback Occurred:', response.fallback_occurred);

🔬 Symbiont AI Gateway — Web-AI Bridge & OpenAI Gateway ($0 Cost)

[!NOTE] CLI & SDK Exclusive Feature: The Symbiont AI Gateway is managed and consumed exclusively via the termes CLI and the terra-termes TypeScript / Node.js SDK.

1. ⚙️ Background Silent Daemon (Zero Terminal Overhead)

Install the silent background service on Windows/Unix to keep http://localhost:7420/v1 always active for Cursor IDE, Python, and cURL without opening terminals:

# Install & start silent background daemon (auto-starts on Windows login)
termes symbiont daemon install

# Check background daemon health
termes symbiont daemon status

# Uninstall & stop daemon
termes symbiont daemon uninstall

2. 🤖 Provider Management with Real-Time Validation

Add AI providers using session credentials with instant validation:

# Add Google Gemini Web (Free/Unlimited)
termes symbiont provider add --type gemini_web --name "Google Gemini" --cookies "<cookies>"

# Add DeepSeek Web (V3 & R1)
termes symbiont provider add --type deepseek_web --name "DeepSeek Web" --token "<userToken>"

# List and manage active providers
termes symbiont provider list
termes symbiont provider update --id <id> --model gemini-3.7-flash
termes symbiont provider delete --id <id>
termes symbiont provider clean

3. 🔑 Termes API Keys Management

Create custom API keys to protect your synthetic public endpoints:

termes symbiont key create --name "Production VIP Key" --key "sk-termes-prod-live-99"
termes symbiont key list
termes symbiont key rename --id <id> --name "New Key Name"
termes symbiont key delete --id <id>

4. 🌐 Public Endpoints: Single Provider vs Multi-Provider Fallback

Deploy synthetic public endpoints backed by ephemeral GitHub Actions relays with configurable idle timeout ($0 cost):

# A. Single Provider Endpoint (No fallback - strictly queries one model engine):
termes symbiont endpoint public create --name "Exclusive Gemini Feed" --providers prov_gemini_web_msuq56vr --api-key "sk-termes-prod-live-99"

# B. Single Provider Endpoint for DeepSeek (Open access):
termes symbiont endpoint public create --name "Exclusive DeepSeek Feed" --providers prov_deepseek_web_msuq58zv --no-auth

# C. Multi-Provider Endpoint with Automatic Fallback Chain:
# (Prioritizes Gemini 3.7; if saturated or session expires, falls back to DeepSeek seamlessly)
termes symbiont endpoint public create --name "Enterprise VIP Feed" --providers prov_gemini_web_msuq56vr,prov_deepseek_web_msuq58zv --api-key "sk-termes-prod-live-99" --timeout 15

# D. Update an existing endpoint's provider chain or timeout:
termes symbiont endpoint public update --id ep_pub_w614r7 --providers prov_deepseek_web_msuq58zv --timeout 30

# E. Generate GitHub Actions Workflow YAML for the serverless relay runner:
termes symbiont endpoint public workflow --id ep_pub_w614r7

# F. List public endpoints and live CDN descriptors:
termes symbiont endpoint public list

# G. Consume endpoint with Smart Auto-Wake (Cold-Start handled automatically):
termes symbiont query --endpoint ep_pub_w614r7 --key sk-termes-prod-live-99 --model gemini-3.7-flash --prompt "¿Qué es el software libre?"

5. 🔌 Consuming via PowerShell, cURL, Python & Cursor IDE

🔵 PowerShell (Native Invoke-RestMethod):

$headers = @{ "Content-Type" = "application/json"; "Authorization" = "Bearer sk-termes-prod-live-99" }
$body = '{"model":"gemini-3.7-flash","messages":[{"role":"user","content":"¿Cuál es la distancia de la Tierra a la Luna?"}]}'

(Invoke-RestMethod -Uri "http://localhost:7420/v1/chat/completions" -Method POST -Headers $headers -Body $body).choices[0].message.content

⚫ CMD / cURL:

curl -X POST http://localhost:7420/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer sk-termes-prod-live-99" -d "{\"model\":\"gemini-3.7-flash\",\"messages\":[{\"role\":\"user\",\"content\":\"Hola\"}]}"

🐍 Python (OpenAI SDK Standard):

from openai import OpenAI

client = OpenAI(base_url="http://localhost:7420/v1", api_key="sk-termes-prod-live-99")
response = client.chat.completions.create(
    model="gemini-3.7-flash", # or "deepseek-chat", "gemini-3.5-flash-lite", "gemini-3.1-pro"
    messages=[{"role": "user", "content": "Resume la historia de la computación"}]
)
print(response.choices[0].message.content)

💻 Cursor IDE (Settings ➔ Models):

• OpenAI Base URL: http://localhost:7420/v1
• OpenAI API Key: sk-termes-prod-live-99
• Model Name: gemini-3.7-flash / gemini-3.5-flash-lite / gemini-3.1-pro / deepseek-chat / deepseek-reasoner

🌐 Live Online Console

Access the official TERMES Web Console hosted on GitHub Pages: 👉 https://amglogicalis.github.io/termes-repo-public/