Trajbl
Documentation

Trajbl setup guide.

Use this page as the practical manual: what Trajbl does, how to test it safely, what to copy into your app, and how to read the results.

Generate API key View benchmarks
Start here

What Trajbl does in one sentence

Trajbl is a hosted context-compression layer that sits between your retrieved context and your final LLM call. It tries to keep the evidence and instructions that matter, remove lower-value wording, and fail open to the original input when compression is unsafe.

Plain English: your app still chooses the documents and still calls the LLM. Trajbl only makes the context smaller before that call, so you can test token savings without rebuilding your whole stack.
1

Choose the app type

Pick Captain Claw or a chat app backend such as OpenAI, Gemini, Ollama, OpenRouter, or LiteLLM. The page then shows the right setup prompt.

2

Generate a pilot key

Enter a name and email, generate the key, and copy it once. The key must stay server-side.

3

Paste the setup prompt

Give the prompt to your coding agent. It will prepare the env values and run safe checks first.

4

Enable only after green light

The agent should report what it checked before you turn Trajbl on in the real workflow.

Pick the right module

Chat apps: OpenAI, Gemini, Ollama, OpenRouter, LiteLLM

Use this for backend apps that send chat-message arrays to an LLM provider. The technical wire format is OpenAI-style messages, but the final provider can be OpenAI, Gemini through an adapter, Ollama, OpenRouter, LiteLLM, vLLM, LM Studio, LocalAI, or a similar backend.

Captain Claw

Use this for the `kstevica/captain-claw` coding-agent workflow. It is a separate module so its usage and pilot keys do not mix with general chat-app testing.

Key rule

The API key is a server-side secret. Treat it like an OpenAI, Anthropic, or Stripe key.

  • Do not paste it into frontend code.
  • Do not commit it to git.
  • Do not print it in logs or screenshots.
  • Do not put it in public examples or documentation.

Environment values

Your agent should add placeholders to the existing server-side env file. You manually paste the real key into `TRAJBL_API_KEY`.

TRAJBL_PROXY_ENABLED=0
TRAJBL_API_URL=https://api.neurobiz.me
TRAJBL_API_KEY=PASTE_TRAJBL_KEY_HERE
TRAJBL_COMPRESSOR=stable
TRAJBL_COMPRESSION_MODE=adaptive
TRAJBL_TIMEOUT_MS=3000
TRAJBL_FAIL_OPEN=1
TRAJBL_LOG_CONTENT=0

Local usage file

The public API tracks usage by API key, but each customer should also keep a local metrics file inside their own project. The setup prompt tells their agent to create it automatically during integration.

# Windows example
C:\Users\You\my-ai-app\.trajbl\metrics.jsonl

# Linux/server example
/opt/my-ai-app/.trajbl/metrics.jsonl

# One JSON line per Trajbl attempt, metrics only:
{
  "timestamp": "2026-07-04T15:00:00Z",
  "enabled": true,
  "raw_input_tokens": 7677,
  "compressed_input_tokens": 4778,
  "token_savings_percent": 37.76,
  "compression_latency_ms": 55,
  "fallback_used": false,
  "compression_mode": "adaptive",
  "hard_context_preserved": true
}

Safe first test

The setup prompt tells your agent to test Trajbl without touching private data or calling a real LLM.

  1. Read the project structure and find the backend provider call.
  2. Check `/health` without a key.
  3. Check `/v1/usage` with the key.
  4. Run `/v1/compress` with a synthetic dummy prompt.
  5. Use a fake downstream provider for the first smoke test.
  6. Report exactly what changed before enabling Trajbl.

Recommended runtime behavior

  • Default off until the user approves the green-light report.
  • Compress only the soft retrieved context, not protected hard context.
  • Fail open to original messages on timeout, quota, invalid response, or low confidence.
  • Write local metrics to `.trajbl/metrics.jsonl` without prompt/message content.
API reference

Only three endpoints matter for the pilot.

GET/healthPublic health check. No API key required.
GET/v1/usageShows the current key identity, quota status, and usage counters.
POST/v1/compressCompresses chat message arrays before the real LLM call.
POST https://api.neurobiz.me/v1/compress
Authorization: Bearer PASTE_TRAJBL_KEY_HERE
Content-Type: application/json

{
  "messages": [
    { "role": "system", "content": "You answer from the provided context only." },
    { "role": "user", "content": "Synthetic test question with dummy context." }
  ],
  "mode": "adaptive"
}

How to read metrics

raw_input_tokensHow many input tokens the original request would send.
compressed_input_tokensHow many input tokens remain after Trajbl compression.
token_savings_percentThe input-token reduction for that request.
fallback_usedTrue means Trajbl passed the original messages through instead of risking damage.
hard_context_preservedTrue means protected technical context stayed intact.
compression_latency_msHow long the compression step took.

What to expect

In controlled support-style workloads, the adaptive wrapper reached about 39% input-token savings while keeping correctness and faithfulness in the high-eighties percentage range.

In controlled long-context benchmark suites, Trajbl showed about 88% context-token reduction and a strong quality-per-token lift over LLMLingua2-style compression.

These are pilot signals, not a universal guarantee. Real results depend on how much long, compressible retrieved context your app sends.

Good fit

  • RAG or support flows with long retrieved articles.
  • Apps that already have a working retrieval step.
  • Agents that send large context blocks to an expensive LLM.
  • Workflows where fail-open behavior is acceptable.

Weak fit

  • Very short prompts where there is little to remove.
  • Pure code, logs, configs, tables, or tool outputs that must stay exact.
  • Systems that expect Trajbl to replace retrieval, ranking, or the final LLM.
  • High-risk production rollout before synthetic and staging tests pass.
Troubleshooting

Most pilot issues are easy to identify.

401The Authorization header is missing or malformed.
403The key is wrong, revoked, inactive, or over quota.
413The request body is too large for the pilot API limits.
429The key is sending requests too quickly.
Low savingsThe input is probably short, code-heavy, log-heavy, or mostly protected hard context.
fallback_used=trueTrajbl chose safety and passed the original input through.