founderlens 0.1.0

Ask your database anything — Python SDK for FounderLens

founderlens

The official Python SDK for FounderLens

Ask your database anything from Python.
Connect your Postgres, MySQL, or SQLite database and get SQL, charts, and AI-powered founder insights in one line of code.

PyPI · Main Repo · Report Bug

---

Installation

pip install founderlens

With pandas support:

pip install founderlens[pandas]

Requires: Python 3.10+ · FounderLens API running locally or hosted

---

Quick Start

from founderlens import FounderLens

# Connect your database
fl = FounderLens()
fl.connect_sqlite("mydata.db")

# Ask anything in plain English
result = fl.ask("Which users signed up last month but never ran a query?")

print(result.insight)
# → "47 users signed up last month and never ran a single query.
#    81% are on the free plan — this is your activation gap."

print(result.action)
# → "Send a 'first query' prompt email to these users on day 3 of signup."

print(result.sql)
# → SELECT u.email, u.plan FROM users u LEFT JOIN ...

# Export results
df = result.to_dataframe()        # pandas DataFrame
result.to_csv("activation.csv")   # Excel-ready CSV
result.to_json()                   # JSON string
result.print_summary()             # formatted console output

---

Connecting to Any Database

# PostgreSQL
fl.connect(
    db_type="postgres",
    host="db.example.com",
    database="myapp",
    username="postgres",
    password="secret",
)

# MySQL / MariaDB
fl.connect(
    db_type="mysql",
    host="db.example.com",
    database="myapp",
    username="root",
    password="secret",
)

# Full connection string (alternative)
fl.connect(connection_string="postgresql://user:pass@host:5432/db")

# SQLite file upload
fl.connect_sqlite("path/to/database.db")

---

Asking Questions

# Single question
result = fl.ask("What is my MRR this month?")

# Multiple questions at once
results = fl.ask_many([
    "How many users signed up this week?",
    "What is my MRR trend for the last 6 months?",
    "Which users are at risk of churning?",
    "What is my trial-to-paid conversion rate?",
    "Which acquisition channel brings the highest LTV users?",
])

for r in results:
    r.print_summary()

---

Exploring Your Schema

schema = fl.schema()
schema.print_schema()

# Output:
# ────────────────────────────────────────────────────────────
#   Database: postgres · 5 tables
# ────────────────────────────────────────────────────────────
#   users        (12,847 rows) — id, email, plan, created_at, last_seen
#   subscriptions (3,204 rows) — id, user_id, plan, mrr, status
#   query_events (89,421 rows) — id, user_id, event_type, created_at
#   revenue        (4,102 rows) — id, user_id, amount, created_at
#   support_tickets  (280 rows) — id, user_id, subject, status
#
#   💡 Suggested questions:
#      • How many users signed up this week vs last week?
#      • What's the breakdown of users by plan?
#      • Which users haven't been active in the last 30 days?

print(schema.table_names())
# ['users', 'subscriptions', 'query_events', 'revenue', 'support_tickets']

---

QueryResult Reference

Every fl.ask() call returns a QueryResult object:

result = fl.ask("Who churned last month?")

# Data
result.question      # "Who churned last month?"
result.sql           # Generated SQL query
result.columns       # ['email', 'plan', 'cancelled_at']
result.rows          # [[...], [...], ...]
result.row_count     # 47

# Visualization
result.chart_type    # 'bar' | 'line' | 'pie' | 'kpi' | 'table'
result.chart_config  # Recharts-compatible config dict

# AI Analysis
result.insight       # Plain-English business summary (2-3 sentences)
result.action        # Specific recommended next action

# Performance
result.execution_ms  # 84

# Export methods
result.to_dataframe()          # → pandas DataFrame
result.to_csv("output.csv")    # → saves CSV file, returns path
result.to_dict()               # → plain Python dict
result.to_json(indent=2)       # → JSON string
result.print_summary()         # → formatted console output

---

Configuration

# Explicit API key
fl = FounderLens(api_key="your_api_key")

# Environment variable (recommended)
# export FOUNDERLENS_API_KEY=your_key
fl = FounderLens()

# Custom server URL (self-hosted)
fl = FounderLens(base_url="https://api.yourapp.com/api/v1")

# Custom timeout (default: 60s)
fl = FounderLens(timeout=120)

---

Context Manager

# Auto-disconnect on exit
with FounderLens() as fl:
    fl.connect_sqlite("mydata.db")
    result = fl.ask("What is my monthly revenue trend?")
    result.to_csv("revenue.csv")
# Connection closed automatically

---

Error Handling

from founderlens import FounderLens
from founderlens.exceptions import (
    ConnectionError,   # Database connection failed
    QueryError,        # SQL generation or execution failed
    AuthError,         # Invalid API key
    RateLimitError,    # Query budget exceeded (free plan)
)

fl = FounderLens()

try:
    fl.connect(db_type="postgres", host="localhost", database="mydb",
               username="postgres", password="secret")
    result = fl.ask("How many users do I have?")
    print(result.insight)

except ConnectionError as e:
    print(f"Could not connect: {e}")
except QueryError as e:
    print(f"Query failed: {e}")
except RateLimitError:
    print("Upgrade to Pro for unlimited queries")

---

Real-World Example

from founderlens import FounderLens
import pandas as pd

fl = FounderLens()
fl.connect(
    db_type="postgres",
    connection_string="postgresql://user:[e-mail]/myapp",
)

# Monday morning metrics in 5 lines
questions = [
    "What is my MRR this month vs last month?",
    "How many users churned this week and why?",
    "Which features are most used by paying customers?",
    "What is my free-to-paid conversion rate this month?",
    "Which users are most at risk of churning?",
]

print("📊 Weekly Business Review\n" + "─" * 40)
for q in questions:
    result = fl.ask(q)
    result.print_summary()
    result.to_csv(f"weekly_{q[:20].replace(' ', '_')}.csv")

---

Installation from Source

git clone https://github.com/GPREETHAMSAXON/founderlens-sdk
cd founderlens-sdk
pip install -e ".[dev]"
pytest tests/ -v

---

Requirements

• Python 3.10+
• requests>=2.28.0
• pandas>=1.5.0 (optional, for to_dataframe())
• FounderLens API server running (local or hosted)

---

Built By

Saxon — B.Tech CSE Final Year, Vignan's Institute of Information Technology
IEEE Vice Chairperson · CGPA 9.03

---

License

MIT License — see LICENSE for details.

---

Part of the FounderLens ecosystem

FounderLens App · GitHub · PyPI