🧠 oneprompt

⚠️ License Notice: This project is licensed under the PolyForm Shield License 1.0.0.

✅ Free for personal use
✅ Free for internal business use
❌ Prohibited to build a competing product or service

For commercial licenses, OEM integration, or questions: contact@oneprompt.com

AI agents for data querying, analysis, and chart generation.

Connect your LLM API key and PostgreSQL database — query data in natural language, run Python analysis, and generate interactive charts in minutes.

⚡ Quick Start

1. Install

Choose the package based on your runtime:

pip install oneprompt-sdk

or:

pip install oneprompt

Prerequisite for oneprompt (full/local only): Docker must be installed and running.

2. Initialize a project

op init

When prompted, choose 0/local for this local Docker quickstart.

This scaffolds your working directory with:

3. Configure

Edit .env with your credentials:

LLM_PROVIDER=google
LLM_API_KEY=your-llm-api-key
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb

Get your Gemini API key at Google AI Studio.

4. Document your schema

Edit DATABASE.md to describe your tables, columns, and relationships. The more detail you provide, the better the AI agent will write SQL queries. See Schema Documentation for the recommended format.

5. Start services

op start

This builds and launches 4 Docker containers:

6. Use it!

import oneprompt as op

client = op.Client()  # Reads from .env automatically

# 1. Query your database with natural language
result = client.query("What are the top 10 products by revenue?")
print(result.summary)
print(result.preview)

# 2. Generate a chart from the results
chart = client.chart("Bar chart of top products", data_from=result)
print(f"Chart saved to: {chart.artifacts[0].path}")

# 3. Run Python analysis
analysis = client.analyze("Calculate month-over-month growth", data_from=result)
print(analysis.summary)

Or run the generated example directly:

python example.py

Cloud-only quickstart (no Docker)

import oneprompt_sdk as op

client = op.Client(oneprompt_api_key="op_live_...")
result = client.query("Top products by revenue", dataset_id="ds_123")
print(result.summary)

📖 Python SDK

Client

The Client class is the main entry point. It reads configuration from .env, environment variables, or explicit parameters:

import oneprompt as op

# Option A: Read from .env (recommended)
client = op.Client()

# Option B: Pass credentials directly
client = op.Client(
    llm_api_key="your-key",
    database_url="postgresql://user:pass@localhost:5432/mydb",
    schema_docs_path="./DATABASE.md",
)

Cloud-only SDK:

import oneprompt_sdk as op

client = op.Client(oneprompt_api_key="op_live_...")

Three core methods

Cloud Dataset Selection

When using cloud mode (ONEPROMPT_API_KEY set), query() supports two dataset sources:

# 1) Stored dataset
result = client.query("Top products by revenue", dataset_id="ds_123")

# 2) Ephemeral dataset (no credential persistence)
result = client.query(
    "Top products by revenue",
    database_url="postgresql://user:pass@host:5432/db",
    schema_docs="# optional schema docs",
)

Rules:

• Use exactly one of dataset_id or database_url.
• schema_docs is supported with database_url in cloud mode.
• Local mode continues to use your configured DATABASE_URL.

AgentResult

Every method returns an AgentResult with:

ArtifactRef

Each artifact in result.artifacts has:

# Read artifact content
artifact = result.artifacts[0]
text = artifact.read_text()    # As string
data = artifact.read_bytes()   # As bytes

Chaining agents

Results can be piped between agents using data_from:

# Query → Chart
data = client.query("Revenue by month for 2025")
chart = client.chart("Line chart of revenue trend", data_from=data)

# Query → Analyze
data = client.query("All transactions this quarter")
stats = client.analyze("Calculate descriptive statistics", data_from=data)

# Query → Analyze → Chart
data = client.query("Daily active users last 90 days")
trend = client.analyze("Calculate 7-day moving average", data_from=data)
chart = client.chart("Line chart with original and smoothed data", data_from=trend)

🌐 REST API

For integration with non-Python applications, start a local API server:

op api

The API runs at http://localhost:8000 with these endpoints:

See docs/reference/rest-api.md for the full API reference.

🖥️ CLI Commands

op init       # Scaffold a new project (.env, DATABASE.md, example.py, docker-compose.yml)
op start      # Build and start all MCP services (Docker Compose)
op stop       # Stop all services
op status     # Check which services are running
op logs       # Tail service logs
op api        # Start the local REST API server

Run op --help for details, or op <command> --help for command-specific options.

🏗️ Architecture

┌─────────────────────────────────────────────┐
│  Your App / SDK Client / REST API           │
├─────────────────────────────────────────────┤
│  AI Agents (Gemini + LangChain)             │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐    │
│  │   Data   │ │  Python  │ │  Chart   │    │
│  │  Agent   │ │  Agent   │ │  Agent   │    │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘    │
├───────┼─────────────┼────────────┼──────────┤
│  MCP Servers (Docker)                       │
│  ┌────┴─────┐ ┌────┴─────┐ ┌────┴─────┐    │
│  │ Postgres │ │  Python  │ │  Chart   │    │
│  │   MCP    │ │   MCP    │ │   MCP    │    │
│  └──────────┘ └──────────┘ └──────────┘    │
├─────────────────────────────────────────────┤
│  Artifact Store (generated file storage)    │
└─────────────────────────────────────────────┘

See docs/architecture/overview.md for the full architecture documentation.

📝 Schema Documentation

For best results, describe your database schema in DATABASE.md. This gives the AI context to write accurate SQL:

# Database Schema

## Tables

### products
| Column | Type | Description |
|--------|------|-------------|
| id | integer | Primary key |
| name | text | Product name |
| price | numeric | Unit price |
| category | text | Product category |

### orders
| Column | Type | Description |
|--------|------|-------------|
| id | integer | Primary key |
| product_id | integer | FK → products.id |
| quantity | integer | Units ordered |
| created_at | timestamp | Order date |

Then point the client to it:

client = op.Client(schema_docs_path="./DATABASE.md")

See docs/guides/schema-docs.md for the complete guide and best practices.

🔧 Configuration

Configuration is loaded in this order (later overrides earlier):

1. .env file in the current directory
2. Environment variables
3. Arguments passed to op.Client()

See docs/guides/configuration.md for the complete reference.

📚 Documentation

Full documentation is available at docs.oneprompt.com or in the docs/ directory:

📄 License

PolyForm Shield License 1.0.0 — see LICENSE for details.