phronesisml 0.2.0__tar.gz

phronesisml-0.2.0/.dockerignore

@@ -0,0 +1,40 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.git/
+.github/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+
+# Tests & docs (not needed in image)
+tests/
+docs/
+notebooks/
+examples/
+*.md
+!README.md
+
+# Dev artifacts
+Phronesis_artifacts/
+phronesisml_artifacts/
+.mlflow/
+mlflow.db
+.pre-commit-config.yaml
+.editorconfig
+.gitignore
+docker-compose.yml
+Makefile
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/

phronesisml-0.2.0/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{toml,cfg,ini}]
+indent_size = 4
+
+[*.{json,yml,yaml}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

phronesisml-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,40 @@
+---
+name: Bug Report
+about: Report a bug to help us improve PhronesisML
+title: "[BUG] "
+labels: bug
+assignees: ""
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Minimal code snippet that reproduces the behavior:
+
+```python
+from phronesisml import Phronesis
+
+ml = Phronesis("your_data.csv")
+ml.run()  # or whichever method fails
+```
+
+**Expected behavior**
+What you expected to happen.
+
+**Actual behavior**
+What actually happened. Include full traceback if applicable.
+
+**Environment**
+- OS: [e.g., Windows 11, Ubuntu 22.04]
+- Python version: [e.g., 3.13.3]
+- PhronesisML version: [e.g., 0.2.0]
+- Installation method: [e.g., pip, source]
+
+**Dataset info**
+- File format: [e.g., CSV, Parquet]
+- Approximate size: [e.g., 500 rows x 20 columns]
+- If possible, attach a minimal sample or describe the schema.
+
+**Additional context**
+Add any other context about the problem here.

phronesisml-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement for PhronesisML
+title: "[FEATURE] "
+labels: enhancement
+assignees: ""
+---
+
+**Is your feature request related to a problem?**
+A clear description of the problem. E.g., "I'm always frustrated when..."
+
+**Describe the solution you'd like**
+A clear description of what you want to happen.
+
+**Describe alternatives you've considered**
+Any alternative solutions or features you've considered.
+
+**Use case**
+Describe the use case this feature would enable. Who benefits and how?
+
+**Additional context**
+Add any other context, code examples, or references here.

phronesisml-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,34 @@
+## Description
+
+Brief description of the changes in this PR.
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that causes existing functionality to change)
+- [ ] Documentation update
+- [ ] Refactoring (no functional changes)
+
+## Checklist
+
+- [ ] My code follows the project's code style (`ruff check` and `ruff format` pass)
+- [ ] I have added/updated tests that prove my fix is effective or my feature works
+- [ ] New and existing tests pass locally (`pytest`)
+- [ ] I have updated the documentation (if applicable)
+- [ ] I have added an entry to `CHANGELOG.md` (if applicable)
+
+## Testing
+
+Describe the tests you ran to verify your changes:
+
+```bash
+pytest tests/ -q
+ruff check phronesisml/ --no-fix
+ruff format --check phronesisml/
+mypy phronesisml/ --ignore-missing-imports
+```
+
+## Screenshots / Output
+
+If applicable, add screenshots or paste test output to demonstrate the change.

phronesisml-0.2.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "ci"
+    commit-message:
+      prefix: "ci"

phronesisml-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,182 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  # ── Auto-format: runs on PRs, commits fixes back to the branch ──
+  auto-format:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: pip install ruff
+      - name: Run ruff fix + format
+        run: |
+          ruff check phronesisml/ --fix
+          ruff format phronesisml/
+      - name: Commit and push if changed
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          if ! git diff --cached --quiet; then
+            git commit -m "style: auto-format with ruff"
+            git push
+          else
+            echo "No formatting changes to commit."
+          fi
+
+  # ── Lint: always runs, fails if code is not clean ───────────────
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: pip install ruff
+      - run: ruff check phronesisml/ --no-fix
+      - run: ruff format --check phronesisml/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: mypy phronesisml/ --ignore-missing-imports
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/ -q --tb=short
+
+  test-api:
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: pip install -e ".[dev,api]"
+      - run: pytest tests/test_api.py -q --tb=short
+
+  test-cli:
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: pip install -e ".[dev,cli]"
+      - run: pytest tests/test_cli_app.py -q --tb=short
+
+  test-explain:
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: pip install -e ".[dev,explain]"
+      - run: pytest tests/test_sdk.py tests/test_simple.py tests/test_explainability.py -q --tb=short
+
+  docker:
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck, test]
+    steps:
+      - uses: actions/checkout@v4
+      - run: docker build -t phronesisml:test .
+      - run: docker run -d --name phronesisml-test -p 8000:8000 phronesisml:test
+      - name: Wait for health endpoint
+        run: |
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:8000/health > /dev/null 2>&1; then
+              echo "Health check passed on attempt $i"
+              exit 0
+            fi
+            echo "Attempt $i/30 failed, retrying in 1s..."
+            sleep 1
+          done
+          echo "Health check failed after 30 attempts"
+          exit 1
+      - name: Stop container
+        if: always()
+        run: docker stop phronesisml-test && docker rm phronesisml-test
+
+  docker-publish:
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck, test, docker]
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - uses: actions/checkout@v4
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Extract tag name
+        id: tag
+        run: echo "version=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: |
+            ghcr.io/${{ github.repository_owner }}/phronesisml:${{ steps.tag.outputs.version }}
+            ghcr.io/${{ github.repository_owner }}/phronesisml:latest
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck, test]
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

phronesisml-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: pip install -e ".[dev]" mkdocs-material "mkdocstrings[python]"
+      - run: mkdocs build --strict
+      - name: Deploy to GitHub Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          mkdocs gh-deploy --force

phronesisml-0.2.0/.gitignore

@@ -0,0 +1,57 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Environment
+.env
+.env.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Distribution
+*.tar.gz
+*.whl
+
+# MLflow
+mlruns/
+mlflow.db
+mlartifacts/
+phronesisml_artifacts/
+Phronesis_artifacts/
+
+# Database files
+*.db
+*.sqlite3
+
+# MkDocs
+site/

phronesisml-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.13
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: ['--maxkb=10000']

phronesisml-0.2.0/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes to PhronesisML will be documented in this file.
+
+> **Note:** This project was formerly known as **AetherML** and published to PyPI as
+> [`aetherml`](https://pypi.org/project/aetherml/). The `aetherml` package on PyPI is
+> now **deprecated** — no new versions will be published there. Install the new package
+> with `pip install phronesisml`.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-07-13
+
+### Changed (Breaking)
+
+- **Project renamed from AetherML to PhronesisML** — The package, CLI, Docker image,
+  and all public-facing names have been updated.
+  - **Package:** `pip install aetherml` → `pip install phronesisml`
+  - **Import:** `from aetherml import AetherML` → `from phronesisml import Phronesis`
+  - **CLI command:** `aetherml run` → `phronesisml run`
+  - **Docker image:** `ghcr.io/kartik00052/phronesisml`
+  - **GitHub repo:** `github.com/kartik00052/PhronesisML`
+- **Class renames:**
+  - `AetherML` → `Phronesis`
+  - `AetherMLConfig` → `PhronesisConfig`
+  - `AetherMLError` → `PhronesisError`
+- **PyPI deprecation:** The `aetherml` package on PyPI is deprecated. New versions will
+  only be published as `phronesisml`. Existing `aetherml` installs are unaffected but
+  will not receive further updates.
+
+---
+
+The entries below document the project's history under its former name, **AetherML**.
+
+## [0.1.3] - 2026-07-13 *(as AetherML)*
+
+### Added
+
+- **`py.typed` marker** (PEP 561) — Downstream users get proper type-checking support from mypy/pyright.
+- **Dependabot config** — Automated weekly dependency-update PRs for pip and GitHub Actions.
+- **Real CI/PyPI badges** in README — Dynamic shields linked to PyPI, GitHub Actions, and license.
+- **Installation matrix** in README — Shows which extras enable which features.
+
+### Changed
+
+- **Version bump to 0.1.3** — Fresh publish to validate Trusted Publisher pipeline end-to-end.
+
+## [0.1.2] - 2026-07-13 *(as AetherML)*
+
+### Added
+
+- **PyPI Trusted Publishing** — CI now publishes to PyPI automatically on `v*` tags via GitHub OIDC (no API tokens stored in secrets).
+- **PyPI CI publish job** — `pypi-publish` in `ci.yml` builds the wheel and pushes to PyPI using `pypa/gh-action-pypi-publish`.
+
+### Changed
+
+- **`openpyxl` and `pyarrow` are now core dependencies** — Excel (.xlsx), Parquet, and Feather files work out of the box with `pip install aetherml`. No manual extra installs needed.
+- **README installation section** rewritten with format support table, extras matrix, and clearer quick-start guidance.
+- **Import error messages** in `pandas_engine.py`, `shap_explainer.py`, and `file_loader.py` updated to reference `pip install aetherml[explain]` instead of raw pip package names.
+
+### Removed
+
+- **Stale manual extras** — Removed separate `[excel]` and `[parquet]` extras (now core). Cleaned up any leftover `[excel]`/`[parquet]` references from v0.1.0.
+
+## [0.1.0] - 2026-07-12 *(as AetherML)*
+
+### Added
+
+- **AetherML class** — High-level SDK facade (`from aetherml import AetherML`) that wraps the full LangGraph pipeline behind method-chained calls (`ml.run()`, `ml.report()`, `ml.train()`). Every method returns typed result objects (`DatasetSummary`, `ValidationReport`, `ModelInfo`, etc.).
+- **Simple API** — Zero-friction one-liner functions (`analyze()`, `train()`, `clean()`, `validate()`, `detect_target()`, `engineer()`, `select_model()`, `explain()`, `report()`) with `async` variants for FastAPI and Jupyter async contexts. Each returns a frozen dataclass with documented fields.
+- **model_type parameter** — Pass `model_type="random_forest"` (or any supported model name) to `AetherML.train()`, `select_model()`, `train()`, or `train_async()` to skip model selection and train a specific model directly.
+- **Incremental execution** — Call individual stages in any order; previously-executed stages are deduplicated and not re-run.
+- **Async loop guard** — `_ensure_sync()` raises `RuntimeError` with a clear message if called from inside a running event loop (FastAPI, Jupyter async), preventing silent hangs.
+- **Jupyter support** — `_repr_html_()` on the `AetherML` class renders a rich summary widget in notebooks.
+- **Degenerate feature handling** — `FeatureEngineeringAgent` now gracefully handles zero-variance, all-null, and single-value columns without crashing, controlled by `FeatureSelectionConfig` (`variance_threshold`, `correlation_threshold`, `min_features`).
+- **Structured exceptions** — `AetherMLError` hierarchy (`DataValidationError`, `EngineSelectionError`, `WorkflowError`, `ConfigurationError`) with structured fields for programmatic error handling.
+- **FastAPI interface** — REST endpoints with multipart file upload, background job execution, job status polling, and OpenAPI docs (`pip install aetherml[api]`).
+- **CLI interface** — Typer-based CLI (`aetherml run`, `aetherml info`) as a thin wrapper around the SDK (`pip install aetherml[cli]`).
+- **PySpark engine** — Optional PySpark data engine for distributed/large-scale datasets (`pip install aetherml[spark]`).
+- **SHAP explainability** — Optional SHAP-based feature importance and model explanation (`pip install aetherml[explain]`).
+- **XGBoost support** — Optional XGBoost model family in the model selection candidate pool (`pip install aetherml[boost]`).
+- **HTML report generation** — `AetherML.generate_report(format="html")` produces a self-contained HTML report.
+- **CI/CD pipeline** — GitHub Actions workflow with lint (ruff), typecheck (mypy), tests (pytest across Python 3.11/3.12/3.13), API tests, CLI tests, explainability tests, Docker build, and GHCR image publishing on tagged releases.
+- **Docker image** — Multi-stage Dockerfile producing a minimal production image, published to `ghcr.io/kartik00052/aetherml`.
+- **Core dependencies required by default** — pandas, polars, numpy, scikit-learn, pydantic, langgraph, and joblib are always installed. Optional extras: `[api]`, `[cli]`, `[spark]`, `[explain]`, `[boost]`, `[mlflow]`.
+- **`python-multipart` in API extras** — Required by FastAPI for file upload parsing; added to the `[api]` extra.
+
+### Changed
+
+- **SDK-first architecture** — CLI and FastAPI are now thin clients that delegate entirely to the SDK; no business logic lives outside the SDK.
+- **WorkflowState** — Expanded to 11 typed fields covering every pipeline stage; agents read/write through this shared state.
+- **`__init__.py` exports** — All public API symbols (Simple API functions, OOP API classes, Advanced API types) are exported from the top-level `aetherml` package.
+- **Mypy strictness** — Enabled `strict = true` with `python_version = "3.13"` and per-module overrides for FastAPI/Typer decorator types.
+
+### Fixed
+
+- **pyproject.toml `[project.urls]` placement** — Moved after `dependencies` to resolve build-system warnings.
+- **GHCR image name casing** — Lowercased to `kartik00052/aetherml` to comply with GitHub Container Registry's all-lowercase requirement.
+- **CI test isolation** — `conftest.py` uses `collect_ignore` to skip `test_api.py` and `test_cli_app.py` when FastAPI/Typer are not installed.
+
+### Known Limitations
+
+- **PDF reports** — `generate_report(format="pdf")` raises `NotImplementedError`. Only Markdown and HTML are supported.
+- **Clustering** — The pipeline is designed for supervised learning (classification/regression). Unsupervised tasks (clustering, dimensionality reduction) are not yet supported.
+- **Time-series** — No special handling for temporal features, forecasting, or time-based train/test splits.
+- **Plugin system** — The `plugins/` directory and entry-points-based discovery mechanism are planned but not yet implemented.
+- **Additional storage backends** — Only local filesystem storage is implemented. S3/GCS/Azure Blob backends are planned.

phronesisml-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,52 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer at kartiksharma18852@gmail.com. All
+complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.