soflytics 0.1.0__tar.gz

soflytics-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: soflytics
+Version: 0.1.0
+Summary: Zero-config data quality for humans. Profile, suggest rules, validate, and visualize — all in one call.
+Author: Saman
+License: MIT
+Project-URL: Homepage, https://github.com/saman/soflytics
+Project-URL: Repository, https://github.com/saman/soflytics
+Keywords: data-quality,profiling,validation,data-engineering
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.20.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: jinja2>=3.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Provides-Extra: db
+Requires-Dist: sqlalchemy>=2.0.0; extra == "db"
+Requires-Dist: pyodbc>=5.0.0; extra == "db"
+Requires-Dist: pymssql>=2.2.0; extra == "db"
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "db"
+Requires-Dist: pymysql>=1.1.0; extra == "db"
+Provides-Extra: all
+Requires-Dist: soflytics[db,dev]; extra == "all"
+
+# 🩺 Soflytics
+
+**Zero-config data quality for humans.**
+
+Point it at any data source — a DataFrame, a CSV — and get instant profiling, smart validation rules, and a gorgeous visual health report. No YAML, no boilerplate.
+
+## Installation
+
+```bash
+pip install soflytics
+```
+
+## Quickstart
+
+```python
+import soflytics
+
+# Audit any data source
+report = soflytics.audit("data.csv")       # CSV file
+report = soflytics.audit(df)               # Pandas DataFrame
+
+# View results
+report.to_console()     # Pretty terminal output
+report.show()           # Opens browser dashboard
+report.to_html("report.html")  # Save standalone HTML
+
+# Smart rule suggestions
+rules = report.suggest()          # Auto-generated rules
+result = report.validate(rules)   # Run validation
+```
+
+## CLI
+
+```bash
+# Audit a CSV file
+soflytics audit data.csv
+
+# Launch interactive dashboard
+soflytics dashboard data.csv
+```
+
+## What You Get
+
+- **🧠 Auto-Profiling** — Nulls, duplicates, outliers, type mismatches, pattern detection
+- **🤖 Smart Rules** — Plain-English rule suggestions based on your data
+- **📊 Visual Dashboard** — Per-column health grades, quality heatmaps, drill-down details
+- **⚡ Dead Simple** — One function call. Zero configuration.
+
+## License
+
+MIT

soflytics-0.1.0/README.md

@@ -0,0 +1,51 @@
+# 🩺 Soflytics
+
+**Zero-config data quality for humans.**
+
+Point it at any data source — a DataFrame, a CSV — and get instant profiling, smart validation rules, and a gorgeous visual health report. No YAML, no boilerplate.
+
+## Installation
+
+```bash
+pip install soflytics
+```
+
+## Quickstart
+
+```python
+import soflytics
+
+# Audit any data source
+report = soflytics.audit("data.csv")       # CSV file
+report = soflytics.audit(df)               # Pandas DataFrame
+
+# View results
+report.to_console()     # Pretty terminal output
+report.show()           # Opens browser dashboard
+report.to_html("report.html")  # Save standalone HTML
+
+# Smart rule suggestions
+rules = report.suggest()          # Auto-generated rules
+result = report.validate(rules)   # Run validation
+```
+
+## CLI
+
+```bash
+# Audit a CSV file
+soflytics audit data.csv
+
+# Launch interactive dashboard
+soflytics dashboard data.csv
+```
+
+## What You Get
+
+- **🧠 Auto-Profiling** — Nulls, duplicates, outliers, type mismatches, pattern detection
+- **🤖 Smart Rules** — Plain-English rule suggestions based on your data
+- **📊 Visual Dashboard** — Per-column health grades, quality heatmaps, drill-down details
+- **⚡ Dead Simple** — One function call. Zero configuration.
+
+## License
+
+MIT

soflytics-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "soflytics"
+version = "0.1.0"
+description = "Zero-config data quality for humans. Profile, suggest rules, validate, and visualize — all in one call."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "Saman"},
+]
+keywords = ["data-quality", "profiling", "validation", "data-engineering"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "pandas>=1.5.0",
+    "fastapi>=0.100.0",
+    "uvicorn>=0.20.0",
+    "rich>=13.0.0",
+    "click>=8.0.0",
+    "jinja2>=3.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+db = [
+    "sqlalchemy>=2.0.0",
+    "pyodbc>=5.0.0",          # SQL Server (Requires ODBC Driver)
+    "pymssql>=2.2.0",         # SQL Server (Portable, no system driver needed)
+    "psycopg2-binary>=2.9.0", # PostgreSQL
+    "pymysql>=1.1.0",         # MySQL
+]
+all = [
+    "soflytics[dev,db]"
+]
+
+[project.scripts]
+soflytics = "soflytics.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/saman/soflytics"
+Repository = "https://github.com/saman/soflytics"
+
+[tool.setuptools.packages.find]
+include = ["soflytics*"]
+
+[tool.setuptools.package-data]
+soflytics = ["dashboard/static/**/*"]

soflytics-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

soflytics-0.1.0/soflytics/__init__.py

@@ -0,0 +1,14 @@
+"""
+Soflytics — Zero-config data quality for humans.
+
+Usage:
+    import soflytics
+    report = soflytics.audit(df)
+    report.show()
+"""
+
+__version__ = "0.1.0"
+
+from soflytics.core import audit
+
+__all__ = ["audit", "__version__"]

soflytics-0.1.0/soflytics/cli.py

@@ -0,0 +1,79 @@
+"""
+Soflytics CLI — command-line interface.
+
+Usage:
+    soflytics audit data.csv
+    soflytics audit data.csv --output html --open
+    soflytics audit sample_data.db --table employees
+    soflytics audit "sqlite:///my.db" --table users
+    soflytics dashboard data.csv
+"""
+
+import click
+
+
+@click.group()
+@click.version_option(version="0.1.0", prog_name="soflytics")
+def main():
+    """🩺 Soflytics — Zero-config data quality for humans."""
+    pass
+
+
+@main.command()
+@click.argument("source")
+@click.option(
+    "--output", "-o",
+    type=click.Choice(["console", "html", "json"]),
+    default="console",
+    help="Output format",
+)
+@click.option("--table", "-t", default=None, help="Database table name (auto-detects if omitted)")
+@click.option("--query", "-q", default=None, help="SQL query to run instead of reading a table")
+@click.option("--html-path", default="soflytics_report.html", help="Path for HTML output")
+@click.option("--open", "open_browser", is_flag=True, help="Open HTML report in browser")
+@click.option("--validate", "run_validate", is_flag=True, help="Also run validation")
+def audit(source, output, table, query, html_path, open_browser, run_validate):
+    """Audit a data source for quality issues.
+
+    SOURCE can be a file path (CSV, Parquet, JSON, Excel, .db) or a database URL
+    (sqlite:///path.db, postgresql://user:pass@host/db, mysql://...).
+    """
+    import soflytics
+
+    click.echo(f"\n  🩺 Auditing: {source}\n")
+
+    report = soflytics.audit(source, table=table, query=query)
+
+    if run_validate:
+        report.validate()
+
+    if output == "console":
+        report.to_console()
+    elif output == "html":
+        path = report.to_html(html_path)
+        click.echo(f"  📄 Report saved: {path}")
+        if open_browser:
+            import webbrowser
+            webbrowser.open(f"file://{path}")
+    elif output == "json":
+        click.echo(report.to_json())
+
+
+@main.command()
+@click.argument("source")
+@click.option("--table", "-t", default=None, help="Database table name")
+@click.option("--port", "-p", default=8765, help="Dashboard port")
+def dashboard(source, table, port):
+    """Launch the interactive dashboard for a data source.
+
+    SOURCE can be a file path or database URL.
+    """
+    import soflytics
+
+    click.echo(f"\n  🩺 Profiling: {source}\n")
+    report = soflytics.audit(source, table=table)
+    report.show(port=port)
+
+
+if __name__ == "__main__":
+    main()

soflytics-0.1.0/soflytics/connectors/__init__.py

@@ -0,0 +1,7 @@
+"""
+Connectors package — auto-detect and load data sources.
+"""
+
+from soflytics.connectors.loader import load
+
+__all__ = ["load"]

soflytics-0.1.0/soflytics/connectors/loader.py

@@ -0,0 +1,134 @@
+"""
+Data source loader — auto-detect and load any supported data source into a Pandas DataFrame.
+"""
+
+import os
+from typing import Optional, Union
+
+import pandas as pd
+
+
+# Known database URL prefixes
+_DB_PREFIXES = (
+    "sqlite:///",
+    "postgresql://",
+    "postgres://",
+    "mysql://",
+    "mysql+pymysql://",
+    "mssql://",
+    "mssql+pyodbc://",
+    "mssql+pymssql://",
+)
+
+
+def load(
+    source: Union[str, pd.DataFrame, "polars.DataFrame"],
+    table: Optional[str] = None,
+    query: Optional[str] = None,
+) -> pd.DataFrame:
+    """
+    Load a data source into a Pandas DataFrame.
+
+    Supported sources:
+        - pandas.DataFrame (pass-through)
+        - polars.DataFrame (auto-convert)
+        - str: file path to CSV, Parquet, JSON, Excel
+        - str: database connection string (sqlite:///..., postgresql://..., mysql://...)
+
+    Args:
+        source: Data source — DataFrame, file path, or database URL.
+        table: Table name to read (for database sources). If omitted, reads the first table found.
+        query: SQL query to execute instead of reading a full table.
+    """
+    # Already a Pandas DataFrame
+    if isinstance(source, pd.DataFrame):
+        return source
+
+    # Polars DataFrame — convert
+    try:
+        import polars as pl
+
+        if isinstance(pl.DataFrame, type) and isinstance(source, pl.DataFrame):
+            return source.to_pandas()
+    except ImportError:
+        pass
+
+    # String — auto-detect: database URL or file path
+    if isinstance(source, str):
+        if any(source.startswith(prefix) for prefix in _DB_PREFIXES):
+            return _load_database(source, table=table, query=query)
+        return _load_file(source)
+
+    raise ValueError(
+        f"Unsupported data source type: {type(source).__name__}. "
+        f"Pass a DataFrame, file path (CSV/Parquet/JSON), or database URL (sqlite:///...)."
+    )
+
+
+def _load_database(
+    url: str,
+    table: Optional[str] = None,
+    query: Optional[str] = None,
+) -> pd.DataFrame:
+    """Load data from a database via SQLAlchemy."""
+    try:
+        from sqlalchemy import create_engine, inspect
+    except ImportError:
+        raise ImportError(
+            "SQLAlchemy is required for database connections. "
+            "Install it with: pip install sqlalchemy"
+        )
+
+    # Auto-fallback to pymssql for SQL Server to avoid ODBC driver issues
+    if url.startswith("mssql://"):
+        url = url.replace("mssql://", "mssql+pymssql://", 1)
+        print("  💡 Auto-switching to pymssql driver for SQL Server (no ODBC needed).")
+
+    engine = create_engine(url)
+
+    # If a custom SQL query is provided, run it directly
+    if query:
+        return pd.read_sql_query(query, engine)
+
+    # If no table name given, auto-detect the first table
+    if not table:
+        inspector = inspect(engine)
+        tables = inspector.get_table_names()
+        if not tables:
+            raise ValueError(f"No tables found in database: {url}")
+        table = tables[0]
+        print(f"  📋 Auto-selected table: '{table}' (found {len(tables)} tables)")
+
+    return pd.read_sql_table(table, engine)
+
+
+def _load_file(path: str) -> pd.DataFrame:
+    """Load a file into a DataFrame based on extension."""
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"File not found: {path}")
+
+    ext = os.path.splitext(path)[1].lower()
+
+    if ext == ".csv":
+        return pd.read_csv(path)
+    elif ext == ".tsv":
+        return pd.read_csv(path, sep="\t")
+    elif ext in (".parquet", ".pq"):
+        return pd.read_parquet(path)
+    elif ext == ".json":
+        return pd.read_json(path)
+    elif ext in (".xlsx", ".xls"):
+        return pd.read_excel(path)
+    elif ext in (".db", ".sqlite", ".sqlite3"):
+        # Auto-detect SQLite file and load via SQLAlchemy
+        return _load_database(f"sqlite:///{os.path.abspath(path)}")
+    else:
+        # Try CSV as fallback
+        try:
+            return pd.read_csv(path)
+        except Exception:
+            raise ValueError(
+                f"Unsupported file format: {ext}. "
+                f"Supported: .csv, .tsv, .parquet, .json, .xlsx, .db"
+            )
+

soflytics-0.1.0/soflytics/core.py

@@ -0,0 +1,40 @@
+"""
+Core module — the main audit() entry point.
+"""
+
+from typing import Optional, Union
+
+import pandas as pd
+
+from soflytics.connectors import load
+from soflytics.profiler import profile
+from soflytics.report.audit_report import AuditReport
+
+
+def audit(
+    source: Union[str, pd.DataFrame],
+    table: Optional[str] = None,
+    query: Optional[str] = None,
+) -> AuditReport:
+    """
+    Audit any data source — profile it, detect issues, suggest rules.
+
+    Usage:
+        report = soflytics.audit("data.csv")
+        report = soflytics.audit(df)
+        report = soflytics.audit("sqlite:///my.db", table="users")
+        report = soflytics.audit("postgresql://localhost/mydb", query="SELECT * FROM orders")
+
+        report.to_console()       # Terminal output
+        report.show()             # Browser dashboard
+        rules = report.suggest()  # Auto-generated rules
+    """
+    # Load data into a DataFrame
+    df = load(source, table=table, query=query)
+
+    # Profile the data
+    profile_result = profile(df)
+
+    # Return an AuditReport
+    return AuditReport(df=df, profile_result=profile_result)
+

soflytics-0.1.0/soflytics/dashboard/__init__.py

@@ -0,0 +1,7 @@
+"""
+Dashboard package — serves the interactive browser UI.
+"""
+
+from soflytics.dashboard.server import launch
+
+__all__ = ["launch"]

soflytics-0.1.0/soflytics/dashboard/app.py

@@ -0,0 +1,7 @@
+"""
+Dashboard — app module (re-exports for convenience).
+"""
+
+from soflytics.dashboard.server import server_app, launch
+
+__all__ = ["server_app", "launch"]

soflytics-0.1.0/soflytics/dashboard/server.py

@@ -0,0 +1,93 @@
+"""
+Dashboard server — FastAPI app and launch function.
+"""
+
+import json
+import os
+import threading
+import time
+import webbrowser
+from typing import TYPE_CHECKING
+
+import uvicorn
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+if TYPE_CHECKING:
+    from soflytics.report.audit_report import AuditReport
+
+# Global reference for the current report
+_current_report = None
+
+server_app = FastAPI(title="Soflytics Dashboard")
+
+# Mount static files
+_static_dir = os.path.join(os.path.dirname(__file__), "static")
+server_app.mount("/static", StaticFiles(directory=_static_dir), name="static")
+
+
+@server_app.get("/", response_class=HTMLResponse)
+async def dashboard():
+    """Serve the main dashboard page."""
+    index_path = os.path.join(_static_dir, "index.html")
+
+    with open(index_path, "r", encoding="utf-8") as f:
+        html = f.read()
+
+    # Inject profile data into the HTML
+    if _current_report:
+        profile_json = json.dumps(_current_report.profile.to_dict(), default=str)
+        rules_json = json.dumps(
+            [r.to_dict() for r in _current_report.suggest()], default=str
+        )
+        html = html.replace("__PROFILE_DATA__", profile_json)
+        html = html.replace("__RULES_DATA__", rules_json)
+
+    return HTMLResponse(content=html)
+
+
+@server_app.get("/api/profile")
+async def get_profile():
+    """Return profile data as JSON."""
+    if _current_report:
+        return JSONResponse(content=_current_report.profile.to_dict())
+    return JSONResponse(content={}, status_code=404)
+
+
+@server_app.get("/api/rules")
+async def get_rules():
+    """Return suggested rules as JSON."""
+    if _current_report:
+        return JSONResponse(
+            content=[r.to_dict() for r in _current_report.suggest()]
+        )
+    return JSONResponse(content=[], status_code=404)
+
+
+@server_app.post("/api/validate")
+async def run_validation():
+    """Run validation with suggested rules and return results."""
+    if _current_report:
+        result = _current_report.validate()
+        # Use json.dumps/loads to ensure numpy types are serializable
+        content = json.loads(json.dumps(result.to_dict(), default=str))
+        return JSONResponse(content=content)
+    return JSONResponse(content={}, status_code=404)
+
+
+def launch(report: "AuditReport", port: int = 8765):
+    """Launch the dashboard server and open the browser."""
+    global _current_report
+    _current_report = report
+
+    def open_browser():
+        time.sleep(1.2)
+        webbrowser.open(f"http://localhost:{port}")
+
+    threading.Thread(target=open_browser, daemon=True).start()
+
+    print(f"\n  🩺 Soflytics Dashboard running at http://localhost:{port}")
+    print(f"  Press Ctrl+C to stop.\n")
+
+    uvicorn.run(server_app, host="127.0.0.1", port=port, log_level="warning")