Metadata-Version: 2.4
Name: founderlens
Version: 0.1.0
Summary: Ask your database anything — Python SDK for FounderLens
Author-email: Saxon <saxon@founderlens.ai>
License: MIT
Project-URL: Homepage, https://founderlens.ai
Project-URL: Documentation, https://docs.founderlens.ai
Project-URL: Repository, https://github.com/GPREETHAMSAXON/founderlens-sdk
Project-URL: Bug Tracker, https://github.com/GPREETHAMSAXON/founderlens-sdk/issues
Keywords: analytics,database,nlp,sql,ai,business-intelligence,natural-language,saas
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Provides-Extra: pandas
Requires-Dist: pandas>=1.5.0; extra == "pandas"
Provides-Extra: all
Requires-Dist: pandas>=1.5.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: responses>=0.25; extra == "dev"

<div align="center">

# founderlens

### The official Python SDK for FounderLens

[![PyPI version](https://img.shields.io/pypi/v/founderlens?style=flat-square&color=e05c2a)](https://pypi.org/project/founderlens)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)
[![Tests](https://img.shields.io/badge/tests-22%20passing-22c55e?style=flat-square&logo=pytest)](./tests)
[![License: MIT](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)](LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/founderlens?style=flat-square&color=blue)](https://pypi.org/project/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**](https://pypi.org/project/founderlens) · [**Main Repo**](https://github.com/GPREETHAMSAXON/founderlens) · [**Report Bug**](https://github.com/GPREETHAMSAXON/founderlens-sdk/issues)

</div>

---

## Installation

```bash
pip install founderlens
```

With pandas support:
```bash
pip install founderlens[pandas]
```

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

---

## Quick Start

```python
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

```python
# 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

```python
# 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

```python
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:

```python
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

```python
# 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

```python
# 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

```python
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

```python
from founderlens import FounderLens
import pandas as pd

fl = FounderLens()
fl.connect(
    db_type="postgres",
    connection_string="postgresql://user:pass@prod-db.example.com/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

```bash
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](LICENSE) for details.

---

<div align="center">

**Part of the FounderLens ecosystem**

[FounderLens App](https://founderlens.ai) · [GitHub](https://github.com/GPREETHAMSAXON/founderlens) · [PyPI](https://pypi.org/project/founderlens)

</div>
