clx-cli 0.6.0

A minimal, backend-agnostic AI resolver with SQL adapters.

clx — Minimal AI Resolver

clx is a lightweight Python library that forwards prompts to your own AI backend. It exposes a single primitive, clx_query, plus a handful of thin task helpers and SQL adapters for Spark, DuckDB, and SQLite. The library never talks directly to OpenAI/Ollama/etc.—you point it at any backend that implements the simple /v1/query contract.

Installation

pip install clx-cli

Backend configuration

Provide a backend URL via (in order of precedence):

1. Function argument: backend_url="https://your-worker.workers.dev"
2. Environment variable: CLX_BACKEND_URL
3. Config file: ~/.clx/config.toml

Example ~/.clx/config.toml:

backend_url = "https://my-backend.company.com"

Default /v1/query contract

POST /v1/query
{
  "model": "...",
  "prompt": "...",
  "params": { ... }
}

Response:
{ "output": ... }  # string or JSON-serializable

Pod/actor worker-style backend

If your backend uses the pods/{podName}/actors/{actorId}/run route (see example below), set CLX_POD_NAME and CLX_ACTOR_ID (or pass pod_name/actor_id to clx_query). Payload will be sent as {"messages": [{"role":"user","content": prompt}], "metadata": {...}} when use_messages_payload=True.

Example endpoint: https://your-worker.workers.dev/pods/{podName}/actors/{actorId}/run

Core usage

from clx import Cache, clx_query

result = clx_query(
    model="meta-llama-3-3-70b-instruct",
    prompt="Summarize: " + text,
    params={"max_tokens": 120, "temperature": 0.3},
    backend_url="https://your-worker.workers.dev",  # optional if CLX_BACKEND_URL/config is set
)
print(result)

Optional caching

Caching is off by default. Pass a Cache instance to enable it (keyed by backend URL + model + prompt + params).

from clx import Cache, clx_query

with Cache() as cache:
    summary = clx_query("meta-llama", "Summarize: " + text, cache=cache)

Worker-style backend usage

from clx import clx_query

result = clx_query(
    model="meta-llama-3-3-70b-instruct",
    prompt="What is 2+2?",
    backend_url="https://your-worker.workers.dev",
    pod_name="ed98786f-0342-4785-9be4-f0b9988ecd27",
    actor_id="3ec7a4b1-2e63-4c05-9ba5-25df471ceefc",
    use_messages_payload=True,
    metadata={"user_id": "user_123"},
)
print(result)  # e.g., "2+2 equals 4."

Paseo backend optimization

clx is optimized to work cleanly with the Paseo backend contract:

• Supports pod/actor routes at https://<paseo-worker>/pods/{podName}/actors/{actorId}/run.
• Uses use_messages_payload=True to send {"messages": [{"role":"user","content": prompt}], "metadata": {...}} which matches Paseo’s expected shape.
• Accepts response or output fields so Paseo responses map directly to return values.
• Environment-friendly defaults: set CLX_BACKEND_URL, CLX_POD_NAME, CLX_ACTOR_ID, and CLX_MODEL (e.g., @cf/meta/llama-3.1-8b-instruct) in .env and invoke clx_query or demo_backend_call.py.

Task helpers

All helpers forward to clx_query with light prompt templates:

• clx_gen(model, prompt, **params)
• clx_summarize(model, text, **params)
• clx_translate(model, text, target_lang, **params)
• clx_classify(model, text, labels, **params)
• clx_extract(model, text, schema, **params)
• clx_similarity(model, a, b, **params)
• clx_fix_grammar(model, text, **params)

Example:

from clx import clx_summarize
summary = clx_summarize("meta-llama3", text, max_tokens=100)

SQL adapters

Each adapter registers clx_query as a SQL function and returns strings (JSON is returned as a stringified payload when expect_json=True).

Spark

from clx.adapters.spark import register_clx_query
register_clx_query(spark, expect_json=True)

df_out = df.selectExpr(
    "clx_query('meta-llama3', CONCAT('Summarize: ', text), named_struct('max_tokens', 120)) AS summary"
)

DuckDB

import duckdb
from clx.adapters.duckdb import register_clx_query

con = duckdb.connect()
register_clx_query(con)

con.execute(\"\"\"
SELECT clx_query(
  'meta-llama3',
  'Translate: ' || text,
  '{"max_tokens": 80}'
) AS translation
FROM docs;
\"\"\")

SQLite

import sqlite3
from clx.adapters.sqlite import register_clx_query

conn = sqlite3.connect(":memory:")
register_clx_query(conn)

conn.execute("SELECT clx_query('meta-llama3', 'Summarize: ' || text, NULL) FROM messages;")

Notes

• clx_query returns either a string or JSON (when expect_json=True, invalid JSON raises ValueError).
• Backend errors surface as RuntimeError with the status code.
• Keep your backend responsible for model selection, routing, and authentication.