soflytics 0.1.0__py3-none-any.whl

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/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/connectors/__init__.py

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

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/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/dashboard/__init__.py

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

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/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")