pychartai 0.5.0__py3-none-any.whl

pychartai/__init__.py

@@ -0,0 +1,504 @@
+"""
+pychartai — AI-powered data analysis and chart generation.
+
+Single public API.  Everything a user needs is available directly under
+``import pychartai as pai``.  The ``pychartai_core`` sub-package is an
+implementation detail and should not be imported directly.
+
+Quick start::
+
+    import pychartai as pai
+
+    llm = pai.OllamaLLM(model='llama3.2')
+    pai.config.set({'llm': llm})
+
+    df = pai.read_csv('data/sales.csv')
+    print(df.chat('What is the average revenue by region?'))
+    df.chat('Plot a bar chart of revenue by region', chart_library='plotly')
+
+    # Data profiling — no LLM needed
+    report = df.profile()
+    print(report.summary)
+
+    # Conversation memory
+    df.enable_memory()
+    df.chat('Total sales by region')
+    df.chat('Now show that as a percentage')
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, Optional
+import pandas as pd
+
+# ---------------------------------------------------------------------------
+# Core imports from implementation package
+# ---------------------------------------------------------------------------
+
+from pychartai_core import config as global_config
+from pychartai_core.providers import (
+    PyChartLLM,
+    OllamaLLM,
+    GitHubLLM,
+    OpenAILLM,
+    GeminiLLM,
+    AnthropicLLM,
+    QwenLLM,
+    DeepSeekLLM,
+    GenericLLM,
+)
+from pychartai_core.smart_df import SmartDataFrame
+from pychartai_core.agent import PyChartAgent, TransformationLog, QueryIntent
+from pychartai_core.sandbox import RestrictedSandbox, DockerSandbox
+from pychartai_core.streaming import StreamEvent
+from pychartai_core.reporter import InsightReporter
+from pychartai_core.skills import Skill, skill
+from pychartai_core.schema import Schema, Column
+from pychartai_core.cache import ResponseCache
+from pychartai_core.memory import ConversationMemory, Turn
+from pychartai_core.profiler import DataProfiler, ProfileReport
+from pychartai_core.themes import ChartTheme, resolve_theme, BUILTIN_THEMES
+from pychartai_core.error_hints import get_hint, format_error_with_hint
+from pychartai_core.model_config import init, load_model_config, get_model, list_models
+from pychartai_core.redactor import DataRedactor
+from pychartai_core.logging import (
+    get_logger, configure_logger, set_log_level,
+)
+from pychartai_core.pipeline import (
+    Pipeline, PipelineStep, PipelineContext,
+    ValidateInput, InjectSchema, InjectSkills,
+    CacheLookup, CallAnalyzer, CallOwnAgent, CacheStore,
+    default_pipeline,
+)
+from pychartai_core.connections import (
+    BaseConnection, CSVConnection, ExcelConnection,
+    JSONConnection, ParquetConnection, SQLConnection,
+    connect,
+)
+from pychartai_core.db_connectors import (
+    PostgreSQLConnection,
+    MySQLConnection,
+    SnowflakeConnection,
+    BigQueryConnection,
+    RedshiftConnection,
+)
+from pychartai_core.cloud_connectors import (
+    S3Connection,
+    GCSConnection,
+    AzureBlobConnection,
+    GoogleSheetsConnection,
+)
+from pychartai_core.visualization import (
+    get_chart_helper_names,
+    list_backends,
+    area_chart,
+    bar_chart,
+    box_chart,
+    bubble_chart,
+    count_chart,
+    ecdf_chart,
+    funnel_chart,
+    heatmap,
+    histogram,
+    kde_chart,
+    line_chart,
+    pairplot_chart,
+    pie_chart,
+    regression_chart,
+    scatter_chart,
+    stacked_bar_chart,
+    step_chart,
+    strip_chart,
+    swarm_chart,
+    violin_chart,
+)
+
+
+
+__version__ = '0.5.0'
+
+# Expose global config singleton under the expected name
+config = global_config
+
+
+# ---------------------------------------------------------------------------
+# Convenience helpers
+# ---------------------------------------------------------------------------
+
+def available_backends() -> tuple[str, ...]:
+    """Return the names of all supported chart backends."""
+    return tuple(list_backends())
+
+
+def available_charts(chart_library: Optional[str] = None) -> tuple[str, ...]:
+    """Return all supported chart helper names, optionally filtered by backend."""
+    return get_chart_helper_names(chart_library)
+
+
+# ---------------------------------------------------------------------------
+# SmartDataFrame alias — canonical class is SmartDataFrame (capital F).
+# SmartDataframe (lower-case f) is kept as a backward-compatible alias.
+# ---------------------------------------------------------------------------
+
+# SmartDataFrame is already imported above; re-export the alias
+SmartDataframe = SmartDataFrame   # backward-compat alias
+
+
+# ---------------------------------------------------------------------------
+# I/O helpers — return SmartDataFrame directly
+# ---------------------------------------------------------------------------
+
+def DataFrame(
+    data: Any = None,
+    *,
+    config: Optional[dict[str, Any]] = None,
+    chart_library: Optional[str] = None,
+    **kwargs: Any,
+) -> SmartDataFrame:
+    """Create a :class:`SmartDataFrame` from any pandas-compatible input.
+
+    Args:
+        data:          Data passed through to :class:`pandas.DataFrame`.
+        config:        Optional dict of pychartai config overrides to apply.
+        chart_library: Default chart backend for this instance.
+        **kwargs:      Forwarded to :class:`pandas.DataFrame`.
+    """
+    if isinstance(data, pd.DataFrame):
+        raw = data
+    elif isinstance(data, SmartDataFrame):
+        raw = data._df
+    else:
+        raw = pd.DataFrame(data, **kwargs)
+    sdf = SmartDataFrame(raw)
+    if chart_library:
+        global_config.set({'chart_backend': chart_library})
+    if config:
+        normalized = dict(config)
+        if 'chart_library' in normalized and 'chart_backend' not in normalized:
+            normalized['chart_backend'] = normalized.pop('chart_library')
+        global_config.set(normalized)
+    return sdf
+
+
+def read_csv(
+    filepath_or_buffer: Any,
+    *,
+    config: Optional[dict[str, Any]] = None,
+    chart_library: Optional[str] = None,
+    **kwargs: Any,
+) -> SmartDataFrame:
+    """Read a CSV file and return a :class:`SmartDataFrame`."""
+    return DataFrame(pd.read_csv(filepath_or_buffer, **kwargs),
+                     config=config, chart_library=chart_library)
+
+
+def read_excel(
+    filepath_or_buffer: Any,
+    *,
+    config: Optional[dict[str, Any]] = None,
+    chart_library: Optional[str] = None,
+    **kwargs: Any,
+) -> SmartDataFrame:
+    """Read an Excel file and return a :class:`SmartDataFrame`."""
+    return DataFrame(pd.read_excel(filepath_or_buffer, **kwargs),
+                     config=config, chart_library=chart_library)
+
+
+def read_json(
+    filepath_or_buffer: Any,
+    *,
+    config: Optional[dict[str, Any]] = None,
+    chart_library: Optional[str] = None,
+    **kwargs: Any,
+) -> SmartDataFrame:
+    """Read a JSON file and return a :class:`SmartDataFrame`."""
+    return DataFrame(pd.read_json(filepath_or_buffer, **kwargs),
+                     config=config, chart_library=chart_library)
+
+
+def read_parquet(
+    filepath_or_buffer: Any,
+    *,
+    config: Optional[dict[str, Any]] = None,
+    chart_library: Optional[str] = None,
+    **kwargs: Any,
+) -> SmartDataFrame:
+    """Read a Parquet file and return a :class:`SmartDataFrame`."""
+    return DataFrame(pd.read_parquet(filepath_or_buffer, **kwargs),
+                     config=config, chart_library=chart_library)
+
+
+# ---------------------------------------------------------------------------
+# Module-level chat() — multi-DataFrame queries
+# ---------------------------------------------------------------------------
+
+def _normalize_df(value: Any) -> pd.DataFrame:
+    """Coerce a SmartDataFrame or plain DataFrame to pd.DataFrame."""
+    if isinstance(value, SmartDataFrame):
+        return object.__getattribute__(value, '_df')
+    if isinstance(value, pd.DataFrame):
+        return value
+    raise TypeError(
+        f'pychartai.chat() expects pandas DataFrame or SmartDataFrame, got {type(value).__name__}'
+    )
+
+
+
+def chat(
+    query: str,
+    *dataframes: Any,
+    sandbox: Optional[Any] = None,
+    chart_library: Optional[str] = None,
+    plot_type: Optional[str] = None,
+    chart_options: Optional[dict[str, Any]] = None,
+    model: Optional[Any] = None,
+    **chart_kwargs: Any,
+) -> str:
+    """Run a natural-language query over one or more DataFrames.
+
+    Call ``.chat()`` directly on a :class:`SmartDataFrame` (recommended)::
+
+        df = pai.read_csv('data.csv')
+        df.chat('Who earns the most?')
+
+    Args:
+        query:        Natural-language question.
+        *dataframes:  One or more :class:`pandas.DataFrame` or
+                      :class:`SmartDataFrame` objects.
+        sandbox:      Optional :class:`RestrictedSandbox` or
+                      :class:`DockerSandbox`.
+        chart_library: Override the visualization backend
+                       ('seaborn', 'matplotlib', 'plotly').
+        plot_type:    Chart type hint (e.g. 'bar', 'line').
+        chart_options: Extra chart keyword options.
+        model:        Optional model override. Can be a preset name,
+                      ``"provider/model"`` string, or a ``PyChartLLM`` instance.
+                      Falls back to global config if omitted.
+        **chart_kwargs: Additional chart parameters.
+
+    Returns:
+        Analysis result as a string, or a chart file path.
+
+    Raises:
+        ValueError:   If no DataFrames are passed.
+        RuntimeError: If no LLM is configured.
+
+    """
+    if not dataframes:
+        raise ValueError('pychartai.chat() requires at least one DataFrame.')
+
+    # Resolve model: explicit > global config
+    llm = None
+    if model is not None:
+        if isinstance(model, (OllamaLLM, GitHubLLM, OpenAILLM, GeminiLLM,
+                              AnthropicLLM, QwenLLM, DeepSeekLLM, GenericLLM)):
+            llm = model
+        elif isinstance(model, str):
+            from pychartai_core.model_config import _MODEL_REGISTRY, get_model, _build_from_provider
+            if model in _MODEL_REGISTRY:
+                llm = get_model(model)
+            elif '/' in model:
+                prov, mname = model.split('/', 1)
+                llm = _build_from_provider(prov, mname)
+            else:
+                raise KeyError(
+                    f"Unknown model {model!r}. Use a preset name from models.yml, "
+                    "'provider/model' format, or a PyChartLLM instance."
+                )
+        else:
+            raise TypeError(f"model must be str or PyChartLLM, got {type(model).__name__}")
+    else:
+        llm = config.get('llm')
+
+    if llm is None:
+        raise RuntimeError(
+            'No LLM configured. '
+            "Use pai.init() at startup, e.g.: pai.init(model='deepseek-v4-flash')"
+        )
+
+    backend = chart_library or config.get('chart_backend', 'seaborn')
+    output_dir = config.get('charts_output_dir', 'exports/charts')
+    directive = SmartDataFrame._build_chart_directive(plot_type, chart_options, chart_kwargs)
+    effective_query = query + directive
+    frames = [_normalize_df(item) for item in dataframes]
+
+    if sandbox is not None:
+        from pychartai_core.agent import PyChartAgent
+        agent = PyChartAgent(llm=llm, chart_backend=backend, charts_output_dir=output_dir)
+        if len(frames) == 1:
+            return agent.chat(effective_query, frames[0])
+        # Multi-DataFrame: merge and query
+        import pandas as _pd
+        merged = _pd.concat(frames, ignore_index=True)
+        return agent.chat(effective_query, merged)
+
+    # Default path: use PyChartAgent
+    from pychartai_core.agent import PyChartAgent
+    agent = PyChartAgent(llm=llm, chart_backend=backend, charts_output_dir=output_dir)
+    if len(frames) == 1:
+        return agent.chat(effective_query, frames[0])
+    import pandas as _pd
+    merged = _pd.concat(frames, ignore_index=True)
+    return agent.chat(effective_query, merged)
+
+
+async def achat(
+    query: str,
+    *dataframes: Any,
+    sandbox: Optional[Any] = None,
+    chart_library: Optional[str] = None,
+    plot_type: Optional[str] = None,
+    chart_options: Optional[dict[str, Any]] = None,
+    **chart_kwargs: Any,
+) -> str:
+    """Async wrapper around :func:`chat`.
+
+    Runs the synchronous call in a thread-pool executor so it can be awaited
+    without blocking the event loop::
+
+        result = await pai.achat('Who earns the most?', df)
+    """
+    import asyncio
+    loop = asyncio.get_event_loop()
+    return await loop.run_in_executor(
+        None,
+        lambda: chat(
+            query,
+            *dataframes,
+            sandbox=sandbox,
+            chart_library=chart_library,
+            plot_type=plot_type,
+            chart_options=chart_options,
+            **chart_kwargs,
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Public API surface
+# ---------------------------------------------------------------------------
+
+__all__ = [
+    '__version__',
+    # Config
+    'config',
+    # LLM providers
+    'PyChartLLM',
+    'OllamaLLM',
+    'GitHubLLM',
+    'OpenAILLM',
+    'GeminiLLM',
+    'AnthropicLLM',
+    'QwenLLM',
+    'DeepSeekLLM',
+    'GenericLLM',
+
+    # DataFrame
+    'SmartDataFrame',
+    'SmartDataframe',        # backward-compat alias
+    'DataFrame',
+    'read_csv',
+    'read_excel',
+    'read_json',
+    'read_parquet',
+    # Agents
+    'PyChartAgent',
+    'TransformationLog',
+    'QueryIntent',
+    # Module-level chat
+    'chat',
+    'achat',
+    # Sandbox & streaming
+    'RestrictedSandbox',
+    'DockerSandbox',
+    'StreamEvent',
+    # Memory
+    'ConversationMemory',
+    'Turn',
+    # Profiling
+    'DataProfiler',
+    'ProfileReport',
+    # Themes
+    'ChartTheme',
+    'resolve_theme',
+    'BUILTIN_THEMES',
+    # Skills
+    'Skill',
+    'skill',
+    # Semantic layer
+    'Schema',
+    'Column',
+    # Cache
+    'ResponseCache',
+    # PII redaction
+    'DataRedactor',
+    # Error hints
+    'get_hint',
+    'format_error_with_hint',
+    # Logging
+    'get_logger',
+    'configure_logger',
+    'set_log_level',
+
+    # Pipeline
+    'Pipeline',
+    'PipelineStep',
+    'PipelineContext',
+    'ValidateInput',
+    'InjectSchema',
+    'InjectSkills',
+    'CacheLookup',
+    'CallAnalyzer',
+    'CallOwnAgent',
+    'CacheStore',
+    'default_pipeline',
+    # Connections
+    'BaseConnection',
+    'CSVConnection',
+    'ExcelConnection',
+    'JSONConnection',
+    'ParquetConnection',
+    'SQLConnection',
+    'connect',
+    # Database connectors
+    'PostgreSQLConnection',
+    'MySQLConnection',
+    'SnowflakeConnection',
+    'BigQueryConnection',
+    'RedshiftConnection',
+    # Cloud storage connectors
+    'S3Connection',
+    'GCSConnection',
+    'AzureBlobConnection',
+    'GoogleSheetsConnection',
+    # Chart helpers (all 20)
+    'area_chart',
+    'bar_chart',
+    'box_chart',
+    'bubble_chart',
+    'count_chart',
+    'ecdf_chart',
+    'funnel_chart',
+    'heatmap',
+    'histogram',
+    'kde_chart',
+    'line_chart',
+    'pairplot_chart',
+    'pie_chart',
+    'regression_chart',
+    'scatter_chart',
+    'stacked_bar_chart',
+    'step_chart',
+    'strip_chart',
+    'swarm_chart',
+    'violin_chart',
+    # Utilities
+    'available_backends',
+    'available_charts',
+    'get_hint',
+    'format_error_with_hint',
+    # Reporting
+    'InsightReporter',
+
+]

pychartai/cli.py

@@ -0,0 +1,91 @@
+"""pychartai.cli — command-line entry point.
+
+    pychartai data.csv "What is the average revenue by region?"
+    pychartai data.csv --profile
+    pychartai data.csv --report report.html
+    pychartai data.csv "Plot revenue by region" --provider openai --model gpt-4o --backend plotly
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+import pychartai as pai
+
+_READERS = {
+    'csv': pai.read_csv,
+    'xlsx': pai.read_excel,
+    'xls': pai.read_excel,
+    'json': pai.read_json,
+    'parquet': pai.read_parquet,
+}
+
+_LLM_BUILDERS = {
+    'ollama': pai.OllamaLLM,
+    'openai': pai.OpenAILLM,
+    'github': pai.GitHubLLM,
+    'qwen': pai.QwenLLM,
+    'gemini': pai.GeminiLLM,
+    'anthropic': pai.AnthropicLLM,
+    'deepseek': pai.DeepSeekLLM,
+}
+
+
+def _load(path: str):
+    ext = path.rsplit('.', 1)[-1].lower() if '.' in path else ''
+    if ext not in _READERS:
+        raise ValueError(f'Unsupported file extension {ext!r}. Supported: {sorted(_READERS)}')
+    return _READERS[ext](path)
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog='pychartai', description=__doc__,
+                                  formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument('file', help='CSV/Excel/JSON/Parquet file to load')
+    ap.add_argument('query', nargs='?', help='Natural-language question (omit with --profile/--report)')
+    ap.add_argument('--provider', default='ollama', choices=sorted(_LLM_BUILDERS))
+    ap.add_argument('--model', default='llama3.2', help='Model name (default: llama3.2)')
+    ap.add_argument('--backend', choices=['seaborn', 'matplotlib', 'plotly'], help='Chart backend override')
+    ap.add_argument('--profile', action='store_true', help='Print an auto-EDA profile (no LLM call)')
+    ap.add_argument('--report', metavar='PATH', help='Write a self-contained HTML insight report to PATH')
+    args = ap.parse_args(argv)
+
+    # Use per-provider default model when the generic default doesn't apply
+    _DEFAULT_MODELS = {
+        'openai': 'gpt-4o',
+        'github': 'gpt-4.1',
+        'qwen': 'qwen-plus',
+        'gemini': 'gemini-2.0-flash',
+        'anthropic': 'claude-3-5-sonnet-20241022',
+        'deepseek': 'deepseek-chat',
+    }
+    if args.model == 'llama3.2' and args.provider in _DEFAULT_MODELS:
+        args.model = _DEFAULT_MODELS[args.provider]
+
+    if not args.query and not args.profile and not args.report:
+        ap.error('provide a query, or pass --profile / --report')
+
+    try:
+        df = _load(args.file)
+    except (ValueError, OSError) as exc:
+        print(f'pychartai: error: {exc}', file=sys.stderr)
+        return 1
+
+    if args.profile:
+        print(df.profile().summary)
+        return 0
+
+    if args.report:
+        path = df.report(args.report)
+        print(f'Report written to {path}')
+        return 0
+
+    pai.config.set({'llm': _LLM_BUILDERS[args.provider](model=args.model)})
+    result = df.chat(args.query, chart_library=args.backend) if args.backend else df.chat(args.query)
+    print(result)
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())