phronesisml 0.2.0__py3-none-any.whl

phronesisml/__init__.py

@@ -0,0 +1,326 @@
+"""Phronesis — public SDK surface.
+
+This is the canonical entry point for programmatic use of Phronesis.
+All public API is exposed here; ``interfaces/cli/`` consumes this
+surface.
+
+Usage::
+
+    # Simple API (recommended for quickstart)
+    from phronesisml import analyze, train
+
+    profile = analyze("data.csv")
+    result = train("data.csv")
+
+    # OOP API
+    from phronesisml import Phronesis
+
+    ml = Phronesis("data.csv")
+    ml.run()
+    print(ml.report())
+
+    # Advanced API (full control)
+    import phronesisml
+
+    result = await phronesisml.run_pipeline(data_path="data.csv")
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from phronesisml.configs.settings import PhronesisConfig
+from phronesisml.exceptions import ConfigurationError, PhronesisError, WorkflowError
+from phronesisml.sdk import (
+    DatasetSummary,
+    EDAReport,
+    EvaluationMetrics,
+    ExplanationReport,
+    FeatureReport,
+    ModelInfo,
+    Phronesis,
+    TargetInfo,
+    ValidationReport,
+)
+from phronesisml.simple import (
+    CleanResult,
+    DatasetProfile,
+    ExplainResult,
+    FeatureResult,
+    ModelResult,
+    TargetResult,
+    TrainResult,
+    ValidationResult,
+    analyze,
+    analyze_async,
+    clean,
+    clean_async,
+    detect_target,
+    detect_target_async,
+    engineer,
+    engineer_async,
+    explain,
+    explain_async,
+    report,
+    report_async,
+    select_model,
+    select_model_async,
+    train,
+    train_async,
+    validate,
+    validate_async,
+)
+from phronesisml.workflow.state import WorkflowState
+
+logger = logging.getLogger(__name__)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # ── Simple API ──────────────────────────────────────
+    "analyze",
+    "analyze_async",
+    "clean",
+    "clean_async",
+    "validate",
+    "validate_async",
+    "detect_target",
+    "detect_target_async",
+    "engineer",
+    "engineer_async",
+    "select_model",
+    "select_model_async",
+    "explain",
+    "explain_async",
+    "report",
+    "report_async",
+    "train",
+    "train_async",
+    "CleanResult",
+    "DatasetProfile",
+    "ExplainResult",
+    "FeatureResult",
+    "ModelResult",
+    "TargetResult",
+    "TrainResult",
+    "ValidationResult",
+    # ── OOP API ─────────────────────────────────────────
+    "Phronesis",
+    "DatasetSummary",
+    "EDAReport",
+    "EvaluationMetrics",
+    "ExplanationReport",
+    "FeatureReport",
+    "ModelInfo",
+    "TargetInfo",
+    "ValidationReport",
+    # ── Advanced API ────────────────────────────────────
+    "PhronesisConfig",
+    "PhronesisError",
+    "ConfigurationError",
+    "WorkflowError",
+    "WorkflowState",
+    "run_pipeline",
+    "__version__",
+]
+
+
+def _compose_agents(
+    config: PhronesisConfig,
+    data_path: str,
+) -> dict[str, Any]:
+    """Manually compose all agents via constructor injection.
+
+    This is the composition root — the only place where concrete agent
+    and engine classes are instantiated.  The rest of the SDK depends
+    on abstractions (``BaseAgent``, ``BaseEngine``).
+
+    All agent imports are deferred to this function so that
+    ``import phronesisml`` does not pull in every dependency eagerly.
+    """
+    from phronesisml.agents.eda.agent import EDAAgent
+    from phronesisml.agents.etl.agent import ETLAgent, ETLConfig
+    from phronesisml.agents.evaluation.agent import EvaluationAgent
+    from phronesisml.agents.explainability.agent import ExplainabilityAgent
+    from phronesisml.agents.feature_engineering.agent import FeatureEngineeringAgent
+    from phronesisml.agents.model_selection.agent import ModelSelectionAgent
+    from phronesisml.agents.reporting.agent import ReportingAgent
+    from phronesisml.agents.storage.agent import StorageAgent
+    from phronesisml.agents.target_detection.agent import TargetDetectionAgent
+    from phronesisml.agents.upload.agent import UploadAgent
+    from phronesisml.agents.validation.agent import ValidationAgent
+    from phronesisml.engines.engine_selector import select_engine
+
+    # Select the computation engine
+    engine = select_engine(config=config, data_path=data_path)
+
+    # Instantiate agents with their dependencies
+    agents: dict[str, Any] = {
+        "upload": UploadAgent(engine=engine),
+        "validation": ValidationAgent(engine=engine),
+        "etl": ETLAgent(config=ETLConfig(null_strategy="drop")),
+        "eda": EDAAgent(engine=engine),
+        "target_detection": TargetDetectionAgent(engine=engine),
+        "feature_engineering": FeatureEngineeringAgent(
+            engine=engine,
+            feature_selection_config=config.feature_selection,
+        ),
+        "model_selection": ModelSelectionAgent(engine=engine),
+        "evaluation": EvaluationAgent(engine=engine),
+        "explainability": ExplainabilityAgent(engine=engine),
+        "reporting": ReportingAgent(),
+        "storage": StorageAgent(),
+    }
+    return agents
+
+
+_FULL_PIPELINE_STAGES: list[str] = [
+    "upload",
+    "etl",
+    "validation",
+    "eda",
+    "target_detection",
+    "feature_engineering",
+    "model_selection",
+    "evaluation",
+    "explainability",
+    "reporting",
+    "storage",
+]
+
+
+async def run_pipeline(
+    data_path: str,
+    engine_preference: str | None = None,
+    null_strategy: str = "drop",
+    stages: list[str] | None = None,
+    config: PhronesisConfig | None = None,
+) -> dict[str, Any]:
+    """Run the Phronesis pipeline on a dataset.
+
+    This is the primary public API.  It:
+    1. Builds configuration (from *config* or defaults).
+    2. Composes agents via manual DI.
+    3. Constructs the LangGraph workflow with the requested stages.
+    4. Executes the graph with the initial state.
+
+    Args:
+        data_path: Path to the input dataset.
+        engine_preference: Force a specific engine (``"pandas"``, ``"polars"``,
+            ``"spark"``).  ``None`` for auto-selection.
+        null_strategy: Null handling strategy (``"drop"``, ``"fill"``, ``"flag"``).
+        stages: Ordered list of pipeline stages to execute.  If ``None``,
+            runs the full pipeline (all 11 stages).
+        config: Optional pre-built configuration.  If ``None``, a config is
+            constructed from the other arguments.
+
+    Returns:
+        A dict summarising the pipeline results.
+
+    Raises:
+        WorkflowError: If the workflow graph execution fails.
+
+    """
+    if config is None:
+        config = PhronesisConfig()
+    if engine_preference is not None:
+        config.engine.preferred = engine_preference
+    if stages is None:
+        stages = list(_FULL_PIPELINE_STAGES)
+
+    logger.info("Phronesis pipeline starting — data_path=%s", data_path)
+
+    # 1–3. Compose agents, build graph, build initial state
+    try:
+        agents = _compose_agents(config, data_path)
+        from phronesisml.workflow.graph import build_graph
+
+        graph = build_graph(agents, stages=stages)
+        initial_state = WorkflowState(data_path=data_path)
+    except WorkflowError:
+        raise
+    except ConfigurationError as exc:
+        msg = f"Pipeline configuration failed: {exc}"
+        logger.exception(msg)
+        raise WorkflowError(msg) from exc
+    except Exception as exc:
+        msg = f"Pipeline setup failed: {exc}"
+        logger.exception(msg)
+        raise WorkflowError(msg) from exc
+
+    # 4. Execute
+    try:
+        final_state = await graph.ainvoke(initial_state)
+    except WorkflowError:
+        raise
+    except Exception as exc:
+        msg = f"Workflow execution failed: {exc}"
+        logger.exception(msg)
+        raise WorkflowError(msg) from exc
+
+    logger.info("Phronesis pipeline complete.")
+
+    # Extract summary from the final state
+    if isinstance(final_state, dict):
+        return _extract_summary(final_state)
+    return _extract_summary(final_state.model_dump())
+
+
+def _extract_summary(state: dict[str, Any]) -> dict[str, Any]:
+    """Build a summary dict from the final workflow state."""
+    processed = state.get("processed_data")
+    validated = state.get("validated_data")
+    profile = state.get("data_profile")
+    best_pipeline = state.get("best_pipeline")
+    evaluation_report = state.get("evaluation_report")
+
+    return {
+        "row_count": state.get("row_count"),
+        "column_count": (
+            len(processed.columns)
+            if processed is not None
+            else (len(validated.columns) if validated is not None else None)
+        ),
+        "transformations": (
+            len(state["transform_log"]) if state.get("transform_log") is not None else 0
+        ),
+        "validation_passed": (
+            state["validation_report"].get("passed")
+            if state.get("validation_report") is not None
+            else None
+        ),
+        "numeric_columns": (profile.get("numeric_columns") if profile is not None else None),
+        "categorical_columns": (
+            profile.get("categorical_columns") if profile is not None else None
+        ),
+        "target_column": state.get("target_column"),
+        "task_type": state.get("task_type"),
+        "target_detection_confidence": state.get("target_detection_confidence"),
+        "ambiguity_reason": state.get("ambiguity_reason"),
+        "n_features": (
+            len(state["feature_names"]) if state.get("feature_names") is not None else None
+        ),
+        "best_model_type": (best_pipeline.get("model_type") if best_pipeline is not None else None),
+        "best_model_score": (best_pipeline.get("score") if best_pipeline is not None else None),
+        "hpo_truncated": (best_pipeline.get("truncated") if best_pipeline is not None else None),
+        "evaluation_metrics": (
+            evaluation_report.get("metrics") if evaluation_report is not None else None
+        ),
+        "evaluation_ambiguity_caveat": (
+            evaluation_report.get("ambiguity_caveat") if evaluation_report is not None else None
+        ),
+        "explanation_sampled": (
+            state["explanation_report"].get("sampled")
+            if state.get("explanation_report") is not None
+            else None
+        ),
+        "explanation_explainer_type": (
+            state["explanation_report"].get("explainer_type")
+            if state.get("explanation_report") is not None
+            else None
+        ),
+        "final_report_length": (
+            len(state["final_report"]) if state.get("final_report") is not None else None
+        ),
+    }

phronesisml/agents/base.py

@@ -0,0 +1,125 @@
+"""Base contracts for the Phronesis agent system.
+
+Every agent in the framework must satisfy the ``BaseAgent`` protocol.
+The protocol uses structural subtyping (``Protocol``) so agents do not
+need to inherit from a base class — they only need to implement the
+required attributes and methods with the correct signatures.
+
+Design rationale:
+- ``Protocol`` over ABC: avoids diamond-inheritance issues when agents
+  also need domain-specific base classes (e.g. domain-specific agents).
+- ``async run``: agents may perform I/O (file reads, DB
+  queries) and async keeps the workflow non-blocking.
+- ``AgentResult``: a lightweight return type that carries the agent's
+  output payload and optional metadata, keeping the contract uniform
+  across all agents regardless of what they produce.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+__all__ = ["AgentResult", "BaseAgent", "Tool"]
+
+from pydantic import BaseModel, Field
+
+from phronesisml.exceptions import AgentNotImplementedError
+
+
+class AgentResult(BaseModel):
+    """Standardised return value from every agent ``run()`` call.
+
+    Attributes:
+        success: Whether the agent completed without error.
+        data: Agent-specific output payload.  The shape varies per agent
+              and is documented in each agent's own module docstring.
+        error: Human-readable error message when ``success`` is False.
+        error_type: Exception class name when ``success`` is False.
+            E.g. ``"DataLoadError"``, ``"ValueError"``.  Survives JSON
+            serialization for non-Python consumers (FastAPI boundary).
+        error_message: Original exception message when ``success`` is False.
+            May differ from ``error`` (which is the agent-wrapped message).
+        error_context: Optional structured context dict for debugging.
+            Keys and values must be strings to survive serialization.
+        metadata: Arbitrary key-value metadata (e.g. row counts, timings).
+
+    """
+
+    success: bool = True
+    data: dict[str, Any] = Field(default_factory=dict)
+    error: str | None = None
+    error_type: str | None = None
+    error_message: str | None = None
+    error_context: dict[str, str] | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class Tool(BaseModel):
+    """Descriptor for a tool an agent exposes to the workflow.
+
+    This is a data descriptor, not a callable — the actual tool
+    implementation lives in the agent; the ``Tool`` object is a
+    serialisable declaration used for discovery and documentation.
+    """
+
+    name: str
+    description: str
+    parameters: dict[str, Any] = Field(default_factory=dict)
+
+
+@runtime_checkable
+class BaseAgent(Protocol):
+    """Protocol that every Phronesis agent must satisfy.
+
+    Agents are stateless with respect to the workflow — all mutable
+    state lives in ``WorkflowState`` and is passed in on every ``run()``
+    call.  This makes agents independently testable and composable.
+    """
+
+    name: str
+    description: str
+
+    async def run(self, state: Any) -> AgentResult:
+        """Execute the agent's core logic against the current workflow state.
+
+        Agents MUST return an ``AgentResult`` — they MUST NOT raise
+        exceptions for expected/transient failures (bad data, missing
+        columns, model failures).  Instead, return
+        ``AgentResult(success=False, error=..., error_type=..., error_message=...)``
+        so the workflow can decide whether to continue or abort.
+
+        Agents SHOULD raise only for programming errors (bugs, missing
+        dependencies) or truly unrecoverable failures (out of memory).
+
+        Args:
+            state: The shared ``WorkflowState`` instance.
+
+        Returns:
+            An ``AgentResult`` carrying the agent's output.
+
+        """
+        ...
+
+    def get_tools(self) -> list[Tool]:
+        """Return the list of tools this agent exposes."""
+        ...
+
+
+class _StubAgent:
+    """Minimal stub that satisfies ``BaseAgent`` for agents not yet implemented.
+
+    This is used only during the initial skeleton pass to validate that
+    the protocol works structurally across all 15 agent directories.
+    It will be replaced by real implementations in subsequent passes.
+    """
+
+    def __init__(self, name: str, description: str) -> None:
+        self.name = name
+        self.description = description
+
+    async def run(self, state: Any) -> AgentResult:
+        msg = f"Agent '{self.name}' has not been implemented yet."
+        raise AgentNotImplementedError(msg)
+
+    def get_tools(self) -> list[Tool]:
+        return []

phronesisml/agents/eda/agent.py

@@ -0,0 +1,113 @@
+"""EDA agent — exploratory data analysis and statistical profiling.
+
+This agent receives the validated DataFrame from the workflow state and
+produces descriptive statistics and distribution analysis using the
+active computation engine:
+
+1. Descriptive statistics per column (min/max/mean/std for numeric;
+   cardinality/top values for categorical).
+2. Dataset-level summary (shape, dtypes, memory usage).
+
+Design:
+- Stateless: all inputs come from ``WorkflowState``.
+- Engine-mediated: all data operations go through ``BaseEngine`` —
+  no direct pandas/polars imports.
+- Thin orchestrator: delegates to ``data.profilers.stats`` for real
+  computation logic.
+- Returns: dict with ``data_profile`` and ``eda_report``
+  that LangGraph merges into the workflow state.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from phronesisml.agents.base import AgentResult, Tool
+from phronesisml.data.profilers.stats import profile_dataset
+from phronesisml.engines.base_engine import BaseEngine
+
+logger = logging.getLogger(__name__)
+
+
+class EDAAgent:
+    """Agent responsible for exploratory data analysis and profiling.
+
+    Args:
+        engine: The active computation engine used for data operations.
+
+    """
+
+    name = "eda"
+    description = "Perform exploratory data analysis and statistical profiling."
+
+    def __init__(self, engine: BaseEngine) -> None:
+        self._engine = engine
+
+    async def run(self, state: Any) -> AgentResult:
+        """Profile ``state.validated_data`` (or ``state.processed_data``).
+
+        Reads from: ``state.validated_data`` (preferred) or
+        ``state.processed_data`` (fallback).
+        Returns: dict with ``data_profile`` and ``eda_report``
+        """
+        data = state.validated_data if state.validated_data is not None else state.processed_data
+        if data is None:
+            return AgentResult(
+                success=False,
+                error="No validated_data or processed_data in workflow state.",
+            )
+
+        try:
+            profile = profile_dataset(data, self._engine)
+
+            eda_report = {
+                "summary": f"Dataset has {profile['shape']['rows']} rows and "
+                f"{profile['shape']['columns']} columns.",
+                "numeric_columns": profile["numeric_columns"],
+                "categorical_columns": profile["categorical_columns"],
+                "memory_bytes": profile["memory_bytes"],
+            }
+
+            logger.info(
+                "EDA complete: %d rows, %d columns, %d numeric, %d categorical.",
+                profile["shape"]["rows"],
+                profile["shape"]["columns"],
+                len(profile["numeric_columns"]),
+                len(profile["categorical_columns"]),
+            )
+            return AgentResult(
+                success=True,
+                data={
+                    "data_profile": profile,
+                    "eda_report": eda_report,
+                },
+                metadata={
+                    "rows": profile["shape"]["rows"],
+                    "columns": profile["shape"]["columns"],
+                },
+            )
+        except Exception as exc:
+            msg = f"Unexpected error during EDA: {exc}"
+            logger.exception(msg)
+            return AgentResult(
+                success=False,
+                error=msg,
+                error_type=type(exc).__name__,
+                error_message=str(exc),
+            )
+
+    def get_tools(self) -> list[Tool]:
+        return [
+            Tool(
+                name="profile_data",
+                description="Compute descriptive statistics and distribution info for a DataFrame.",
+                parameters={
+                    "columns": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Specific columns to profile (default: all).",
+                    },
+                },
+            ),
+        ]