guepard-relml

RelML is a natural-language agent over your relational database. You ask a question in plain English; it inspects your schema, decides what to predict, trains a model on your data, checks itself against held-out rows, and answers — no ML code and no feature engineering on your side.

• CLI: relml-agent — an interactive assistant for your database.
• Python: the Agent class — the same power, embeddable in your code.

Table of contents

1. Install
2. Configure the model backend
3. Connect your data
4. Command line
5. Python API
6. How it works
7. Troubleshooting
8. License

Install

Requires Python 3.9+. Always install into a virtual environment:

python3 -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
pip install guepard-relml

Verify it imported and the CLI is on your PATH:

python -c "import guepard.qwery.relml._relml_core as c; print('core ok:', hasattr(c, 'train'))"
relml-agent --help

Debian/Ubuntu: if pip install prints error: externally-managed-environment, you skipped the virtual environment. The venv steps above are the fix — do not use --break-system-packages.

Configure the model backend (AWS Bedrock)

The agent is powered by Claude on AWS Bedrock. Provide credentials as environment variables, or put them in a .env file in the directory you run relml-agent from:

export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key
export AWS_REGION=us-east-1
export RELML_AGENT_MODEL=us.anthropic.claude-sonnet-4-5-20250929-v1:0

Before the first run, open the Bedrock console → Model access and make sure the Claude model above is enabled for your region.

Other backends. RelML can also use the Anthropic API directly (RELML_AGENT_BACKEND=anthropic, ANTHROPIC_API_KEY=…) or Ollama (RELML_AGENT_BACKEND=ollama, OLLAMA_API_KEY=…).

Connect your data

Tell RelML where your data lives via --source (CLI) or the first argument to Agent(...) (Python). Three source types are supported.

1. A PostgreSQL database

Pass a connection string — libpq keyword form or a URL. The database is opened read-only; RelML never writes to it.

relml-agent --source "dbname=mydb host=localhost user=me password=secret"
relml-agent --source "postgresql://me:secret@localhost:5432/mydb"

The first Postgres run downloads DuckDB's postgres extension, so it needs network access once.

2. A folder of CSV / Parquet files

Every .csv / .parquet file in the folder becomes a table (named after the file). Great for quick experiments.

relml-agent --source ./my_data

3. A single CSV / Parquet file

relml-agent --source ./sales.parquet

Command line

relml-agent has two modes.

Interactive — omit the question to open a REPL you can converse with:

relml-agent --source ./my_data

One-shot — pass a question to get a single answer and exit:

relml-agent "which customers are most likely to churn next month?" --source ./my_data

Run relml-agent --help for the full flag list.

REPL commands

Inside the interactive session, type a question, or a /command (these inspect state without spending model calls):

A typical session

$ relml-agent --source ./ecommerce
› /tables
  customers (12,043 rows, pk customer_id)
  orders    (98,220 rows, pk order_id, fk customer_id → customers)
  ...
› will customer 5512 order again in the next 30 days?
  [the agent explores the data, trains a model, and answers with a probability]
› /plot
  [actual vs predicted over the backtest]
› /quit

Python API

from guepard.tools.agent import Agent

# source: a CSV/Parquet folder, a single file, or a Postgres connection string
agent = Agent("./my_data")

answer = agent.ask("Forecast next week's daily order volume.")
print(answer)

Quiet mode — suppress the live progress output (useful in scripts/services):

agent = Agent("./my_data", verbose=False)
print(agent.ask("Rank customers by churn risk."))

Choose the backend/model in code (overrides the environment):

from guepard.tools.agent import Agent, LLMClient

client = LLMClient(backend="bedrock",
                   model="us.anthropic.claude-sonnet-4-5-20250929-v1:0")
agent = Agent("dbname=mydb host=localhost user=me password=secret", client=client)
print(agent.ask("Which drivers are most at risk of a DNF next race?"))

Agent(...) options

agent.ask(question: str) -> str returns the final natural-language answer.

How it works

From one question, RelML runs a loop: describe your schema and key graph → explore the data with read-only SQL → frame a supervised task (target, features, train/validation split) → train a model → evaluate it against held-out rows and leakage-free baselines → iterate until the gains are marginal → answer you in plain language. Predictions can be written back as a queryable table so you can inspect them with /sql.

Troubleshooting

License

MIT