RedpillX

Natural language in. Deterministic chart data out.

RedpillX is a cross-language SDK that turns natural-language questions and arbitrary JSON into validated chart specifications and renderer-independent data.

The core design keeps probabilistic reasoning separate from deterministic execution:

1. RedpillX flattens and profiles the input data.
2. Your LLM receives a compact profile and bounded sample—not the complete dataset.
3. The generated ChartSpec is validated with Zod or Pydantic.
4. A local Polars executor applies filters, time ranges, grouping, aggregation, sorting and limits to the complete dataset.
5. The result can be rendered with any chart library.

The LLM decides what to visualize. RedpillX decides how to transform the data.

Packages

This repository coordinates two independently versioned SDKs through Git submodules.

SDK	Workspace	Package	Runtime	Validation and execution
TypeScript	packages/js	redpillx	Node.js 18+	Zod + nodejs-polars
Python	packages/python	redpillx	Python 3.10+	Pydantic + Polars

Both implementations share the same pipeline and chart contract while following the conventions of their language ecosystems.

Why RedpillX?

• Bring your own LLM — connect any provider through a small caller-supplied function.
• Keep execution local — the LLM plans from a profile and sample; the full transformation runs in Polars.
• Use a portable contract — typed ChartSpec output is independent of the selected model and chart renderer.
• Handle real API data — flatten nested JSON and normalize numeric, currency and date values.
• Express analytical intent — support filters, relative or absolute time ranges, grouping, aggregation, sorting, limits and series.
• Render anywhere — adapt the output to Recharts, Chart.js, ECharts, ApexCharts, Plotly, D3 or another visualization library.

Installation

TypeScript

npm install redpillx

Python

pip install redpillx

Quick start

TypeScript

import { Redpill } from "redpillx";

const redpill = new Redpill()
  .setLlm(myLlmFunction)
  .sampleSize(30)
  .build();

const data = {
  tickets: [
    { status: "open", priority: "high" },
    { status: "closed", priority: "low" },
    { status: "open", priority: "medium" },
  ],
};

const { spec } = await redpill.generateSpec(
  data,
  "show ticket count by status",
);

const result = redpill.execute(spec, data);
console.log(result.data);

See the TypeScript SDK documentation for the LLM function contract and complete API.

Python

from redpillx import Redpill

redpill = (
    Redpill()
    .llm(my_llm_function)
    .sample_size(30)
    .build()
)

data = {
    "tickets": [
        {"status": "open", "priority": "high"},
        {"status": "closed", "priority": "low"},
        {"status": "open", "priority": "medium"},
    ]
}

generated = redpill.generate_spec(
    data=data,
    prompt="show ticket count by status",
)

result = redpill.execute(spec=generated.spec, data=data)
print(result.data)

See the Python SDK documentation for the LLM callable contract and complete API.

Shared architecture

Natural-language request + JSON
              |
              v
     Flatten and profile data
              |
              v
  Profile + bounded sample -> Your LLM
              |
              v
      Validated ChartSpec
              |
              v
   Local deterministic executor
              |
              v
 Renderer-independent chart data

The ChartSpec describes:

• chart type and axes;
• optional series and presentation metadata;
• filters and time ranges;
• grouping and aggregation;
• sorting and result limits.

The executor returns normalized { x, y, series? } rows with metadata, warnings and record counts. See the chart specification reference for the full contract.

Working with the repository

Clone the workspace with both SDKs:

git clone --recurse-submodules https://github.com/Msalways/red-pill.git
cd red-pill

If the repository was cloned without submodules:

git submodule update --init --recursive

TypeScript development

cd packages/js/redpill
npm install
npm test
npm run build

Python development

cd packages/python/redpillx
pip install -e ".[dev]"
pytest tests -v

Documentation

• Chart specification and renderer contract
• TypeScript SDK
• Python SDK
• Chart-library integration guide
• Release process

License

RedpillX is available under the MIT License. See the license included with each SDK package.