predikit 0.4.0__tar.gz → 0.4.2__tar.gz

{predikit-0.4.0 → predikit-0.4.2}/.claude/settings.local.json

@@ -3,7 +3,8 @@
     "allow": [
       "Bash(git add *)",
       "Bash(git commit -m ' *)",
-      "Bash(python -m pytest tests/ -v --tb=short --cov=src/predikit --cov-report=term-missing)"
+      "Bash(python -m pytest tests/ -v --tb=short --cov=src/predikit --cov-report=term-missing)",
+      "WebFetch(domain:github.com)"
     ]
   }
 }

predikit-0.4.2/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

predikit-0.4.2/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

{predikit-0.4.0 → predikit-0.4.2}/.github/workflows/publish.yml

@@ -4,11 +4,15 @@ on:
   release:
     types: [published]
 
+permissions:
+  contents: read
+
 jobs:
   publish:
     runs-on: ubuntu-latest
     environment: pypi
     permissions:
+      contents: read
       id-token: write
 
     steps:

{predikit-0.4.0 → predikit-0.4.2}/.github/workflows/test.yml

@@ -6,7 +6,31 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Ruff lint
+        run: ruff check src/ tests/
+
+      - name: Ruff format check
+        run: ruff format --check src/ tests/
+
+      - name: Mypy
+        run: mypy src/predikit
+
   test:
     runs-on: ubuntu-latest
     strategy:

{predikit-0.4.0 → predikit-0.4.2}/.gitignore

@@ -10,3 +10,4 @@ htmlcov/
 .venv/
 venv/
 *.egg
+file.py

predikit-0.4.2/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - pydantic>=2.0
+          - numpy>=1.24

predikit-0.4.2/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.2] - 2026-06-13
+
+### Changed
+- Redesigned PyPI/README hero: logo, centered tagline, and badges in a unified `<p align="center">` block
+- Tagline moved from a `##` heading to a proper descriptive paragraph
+- Badges converted to centered HTML `<img>` links for consistent rendering on PyPI
+- Quick code teaser repositioned directly below badges (before Table of Contents)
+- "Field naming rule" added to Table of Contents
+- `ainvoke()` added to `ModelTool` Core API reference table
+- `ModelEnsemble` Core API subsection added with constructor signature and full strategy table
+- Project Traffic / download badge moved to bottom of README
+- Development Status classifier bumped from `3 - Alpha` to `4 - Beta` in `pyproject.toml`
+- Removed CI test status badge from README
+
+## [0.4.1] - 2026-06-02
+
+### Added
+- `ruff` (lint + format) and `mypy` (type checking) configured in `pyproject.toml`
+- `.pre-commit-config.yaml` — ruff and mypy hooks run automatically before every commit
+- Lint CI job in GitHub Actions — runs `ruff check`, `ruff format --check`, and `mypy` on every push and PR
+- `CONTRIBUTING.md` — development setup, code style, and PR guidelines
+- `CHANGELOG.md`
+- `CLAUDE.md` — project context for Claude Code
+
+### Changed
+- Bumped version to `0.4.1`
+- Added `ruff>=0.4.0`, `mypy>=1.10`, and `pre-commit>=3.0` to `[dev]` extras
+
+## [0.4.0] - 2026-05-01
+
+### Added
+- `ModelEnsemble` with `weighted_mean` and `weighted_vote` strategies
+- `ainvoke()` async wrapper on `ModelTool` (runs blocking predict in a thread pool)
+- Verbose logging via `verbose=True` on `ModelTool`
+- Snowflake Model Registry loader (`from_snowflake`)
+- MLflow Model Registry loader (`from_mlflow`)
+- `predikit inspect` CLI command
+
+### Changed
+- Moved to `src/` layout with hatchling build backend
+- Upgraded Pydantic dependency to v2
+
+## [0.3.x] and earlier
+
+See [GitHub Releases](https://github.com/Tejas-TA/predikit/releases) for earlier history.

predikit-0.4.2/CLAUDE.md

@@ -0,0 +1,71 @@
+# predikit — Claude Code context
+
+## What this is
+
+predikit wraps fitted scikit-learn / XGBoost models as LLM-callable tools with auto-generated JSON schemas, typed I/O via Pydantic, and first-class support for OpenAI function calling and LangChain.
+
+## Project layout
+
+```
+src/predikit/          Core package (installed as `predikit`)
+  tool.py              ModelTool — main public class
+  registry.py          ToolRegistry — groups multiple tools for bulk export
+  ensemble.py          ModelEnsemble — multi-model reconciliation strategies
+  exceptions.py        LowConfidenceError
+  coerce.py            LLM-string → Python type coercion (bool, int, float, str)
+  introspect.py        Extract sklearn model metadata (feature names, task type)
+  cli.py               `predikit inspect` CLI (click + joblib)
+  exporters/
+    openai.py          .to_openai() — OpenAI function-calling schema
+    langchain.py       .to_langchain() — LangChain StructuredTool
+  loaders/
+    mlflow.py          from_mlflow() — load from MLflow Model Registry
+    snowflake.py       from_snowflake() — load from Snowflake Model Registry
+tests/                 pytest suite (mirrors src/ layout)
+examples/              Standalone usage scripts (01–07)
+```
+
+## Commands
+
+```bash
+# Install for development
+pip install -e ".[dev]"
+
+# Run tests
+pytest --cov=src/predikit --cov-report=term-missing
+
+# Lint (check only)
+ruff check src/ tests/
+
+# Format (check only)
+ruff format --check src/ tests/
+
+# Lint + format (auto-fix)
+ruff check --fix src/ tests/
+ruff format src/ tests/
+
+# Type check
+mypy src/predikit
+
+# All checks via pre-commit
+pre-commit run --all-files
+
+# Install pre-commit hooks
+pre-commit install
+```
+
+## Key conventions
+
+- **Public API** — `ModelTool`, `ToolRegistry`, `ModelEnsemble`, `LowConfidenceError` are all re-exported from `predikit/__init__.py`. Everything else is internal.
+- **Optional imports** — heavy optional deps (`langchain`, `xgboost`, `mlflow`, `snowflake`) are imported inside functions/methods, never at module level, so missing extras don't break core imports.
+- **Feature name matching** — inputs map to model features by column name (using `feature_names_in_` from sklearn), not by position. Mismatches raise a `ValueError` with a clear diff.
+- **Bool coercion** — `coerce_value()` converts LLM strings (`"yes"`, `"true"`, `"1"`, `"on"`) to Python bools before Pydantic validation.
+- **Async** — `ainvoke()` is a thin wrapper over `invoke()` via `loop.run_in_executor`. No async-native I/O involved.
+- **Ensemble strategies** — `"collect"`, `"mean"`, `"vote"`, `"weighted_mean"`, `"weighted_vote"`. Weighted strategies take a `weights` list parallel to `tools`.
+
+## Release process
+
+1. Bump `version` in `pyproject.toml` and `__version__` in `src/predikit/__init__.py`.
+2. Add a section to `CHANGELOG.md`.
+3. Commit, push to `main`, create a GitHub Release with the version tag (e.g. `v0.4.1`).
+4. `publish.yml` auto-triggers a PyPI upload via OIDC trusted publishing.

predikit-0.4.2/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing to predikit
+
+Thanks for your interest in contributing.
+
+## Prerequisites
+
+- Python 3.10+
+- [pre-commit](https://pre-commit.com/) (`pip install pre-commit`)
+
+## Development setup
+
+```bash
+git clone https://github.com/Tejas-TA/predikit
+cd predikit
+pip install -e ".[dev]"
+pre-commit install
+```
+
+`pre-commit install` wires up ruff and mypy to run automatically before every commit.
+
+## Running tests
+
+```bash
+pytest --cov=src/predikit --cov-report=term-missing
+```
+
+## Code style
+
+This project uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting, and [mypy](https://mypy.readthedocs.io/) for type checking. All three are configured in `pyproject.toml`.
+
+```bash
+# Check and auto-fix
+ruff check --fix src/ tests/
+ruff format src/ tests/
+
+# Type check
+mypy src/predikit
+```
+
+Or run everything at once via pre-commit:
+
+```bash
+pre-commit run --all-files
+```
+
+CI enforces all three checks on every push and PR (see `.github/workflows/test.yml`).
+
+## Pull request guidelines
+
+- Target `main`.
+- Keep changes focused — one feature or fix per PR.
+- Add or update tests for any changed behaviour.
+- Run `pre-commit run --all-files` before pushing; CI will catch failures regardless.
+
+## Adding a new exporter or loader
+
+- Exporters live in `src/predikit/exporters/` and should expose a single function consumed by `ModelTool`.
+- Loaders live in `src/predikit/loaders/` and should return a `ModelTool` instance.
+- Any new optional dependency must be added to both the relevant optional group and `dev` in `pyproject.toml`, and imported inside the function body (not at module level).
+
+## Release process (maintainers)
+
+1. Bump `version` in `pyproject.toml` and `__version__` in `src/predikit/__init__.py`.
+2. Add a section to `CHANGELOG.md`.
+3. Merge to `main`, create a GitHub Release tagged `vX.Y.Z`.
+4. `publish.yml` automatically publishes to PyPI via OIDC trusted publishing.

{predikit-0.4.0 → predikit-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: predikit
-Version: 0.4.0
+Version: 0.4.2
 Summary: Turn any trained sklearn/XGBoost model into an LLM-callable tool with auto-generated schemas and typed I/O.
 Project-URL: Homepage, https://github.com/Tejas-TA/predikit
 Project-URL: Repository, https://github.com/Tejas-TA/predikit
@@ -10,7 +10,7 @@ Author-email: Tejas Tumakuru Ashok <tejasta@gmail.com>
 License: MIT
 License-File: LICENSE
 Keywords: agents,function-calling,llm,ml-tools,sklearn,xgboost
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
@@ -31,9 +31,12 @@ Requires-Dist: click>=8.0; extra == 'dev'
 Requires-Dist: joblib>=1.2; extra == 'dev'
 Requires-Dist: langchain-core>=0.1; extra == 'dev'
 Requires-Dist: mlflow>=2.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pandas>=1.5; extra == 'dev'
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
 Requires-Dist: xgboost>=1.7; extra == 'dev'
 Provides-Extra: langchain
 Requires-Dist: langchain-core>=0.1; extra == 'langchain'
@@ -45,13 +48,30 @@ Provides-Extra: xgboost
 Requires-Dist: xgboost>=1.7; extra == 'xgboost'
 Description-Content-Type: text/markdown
 
-# predikit
-[![PyPI version](https://img.shields.io/pypi/v/predikit.svg)](https://pypi.org/project/predikit/)
-[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-
-
-Turn any trained scikit-learn or XGBoost model into an LLM-callable tool — auto-generated JSON schemas, typed I/O, zero boilerplate.
+<p align="center">
+  <picture>
+    <source srcset="https://raw.githubusercontent.com/Tejas-TA/predikit/main/docs/logo.gif">
+    <img src="https://raw.githubusercontent.com/Tejas-TA/predikit/main/docs/logo.png" alt="predikit" width="500"/>
+  </picture>
+</p>
+
+<p align="center">
+  Turn any trained scikit-learn or XGBoost model into an LLM-callable tool —<br/>
+  auto-generated JSON schemas, typed I/O, zero boilerplate.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/predikit/"><img src="https://img.shields.io/pypi/v/predikit.svg" alt="PyPI version"/></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+"/></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"/></a>
+  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"/></a>
+</p>
+
+<p align="center">
+  <a href="https://pepy.tech/project/predikit"><img src="https://static.pepy.tech/personalized-badge/predikit?period=week&units=international_system&left_color=grey&right_color=blue&left_text=weekly+downloads" alt="Weekly Downloads"/></a>
+  <a href="https://pepy.tech/project/predikit"><img src="https://static.pepy.tech/personalized-badge/predikit?period=month&units=international_system&left_color=grey&right_color=blue&left_text=monthly+downloads" alt="Monthly Downloads"/></a>
+  <a href="https://pepy.tech/project/predikit"><img src="https://static.pepy.tech/personalized-badge/predikit?period=total&units=international_system&left_color=grey&right_color=blue&left_text=total+downloads" alt="Total Downloads"/></a>
+</p>
 
 ```python
 tool = ModelTool(model=clf, name="classify_iris", ...)
@@ -59,6 +79,15 @@ tool.to_openai()              # OpenAI function schema, ready to pass to the API
 tool.invoke({"sqft": 2200})   # → {"price_usd": 370730}
 ```
 
+## Table of Contents
+- [Install](#install)
+- [30-second example](#30-second-example)
+- [Core API](#core-api)
+- [Field naming rule](#field-naming-rule)
+- [Cookbook](#cookbook)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Install
 
 ```bash
@@ -136,6 +165,7 @@ ModelTool(
 | Method | Returns | What it does |
 |--------|---------|--------------|
 | `.invoke(input_dict)` | `dict` | Validates → predicts → returns `{output_name: value}` |
+| `.ainvoke(input_dict)` | `dict` | Async version of `.invoke()` |
 | `.to_openai()` | `dict` | OpenAI function-calling schema |
 | `.to_langchain()` | `StructuredTool` | LangChain tool |
 | `.to_callable()` | `Callable` | Plain Python function |
@@ -151,6 +181,30 @@ registry.to_langchain()  # → list[StructuredTool]
 registry.get("name")     # → ModelTool
 ```
 
+### `ModelEnsemble`
+
+Call multiple models and reconcile their outputs in one step:
+
+```python
+ModelEnsemble(
+    tools: list[ModelTool],   # models to run in parallel
+    name: str,                # ensemble tool name the LLM sees
+    description: str,
+    strategy: str,            # "collect" | "mean" | "vote" | "weighted_mean" | "weighted_vote"
+    weights: list[float],     # optional, for weighted strategies
+)
+```
+
+| Strategy | Behaviour |
+|----------|-----------|
+| `"collect"` | Merges all outputs into one dict (tools can have different `output_name`) |
+| `"mean"` | Averages numeric outputs (all tools must share `output_name`) |
+| `"vote"` | Majority class vote (all tools must share `output_name`) |
+| `"weighted_mean"` | Weighted average — provide a `weights` list |
+| `"weighted_vote"` | Weighted majority vote — provide a `weights` list |
+
+`ModelEnsemble` exposes the same `.invoke()`, `.ainvoke()`, `.to_openai()`, and `.to_langchain()` interface as `ModelTool`.
+
 ## Field naming rule
 
 **Your Pydantic schema field names must exactly match the column names the model was trained on.**
@@ -270,8 +324,6 @@ Only applies to classifiers that implement `predict_proba`. Regressors are unaff
 
 ### Multi-model ensemble
 
-Call multiple models and reconcile their outputs in one step:
-
 ```python
 from predikit import ModelEnsemble, ToolRegistry
 
@@ -286,12 +338,6 @@ result  = ensemble.invoke(inputs)  # → {"price_usd": 370112}
 schema  = ensemble.to_openai()     # works exactly like ModelTool
 ```
 
-| strategy | behaviour |
-|----------|-----------|
-| `"collect"` | merges all outputs into one dict (tools can have different `output_name`) |
-| `"mean"` | averages numeric outputs (all tools must share `output_name`) |
-| `"vote"` | majority class vote (all tools must share `output_name`) |
-
 Register ensembles alongside individual tools:
 
 ```python
@@ -333,7 +379,7 @@ tool = from_snowflake(
     model_name="VACATION_CHURN",
     model_version="V3",
     name="churn_risk",
-    description="Vacation ownership churn classifier.",
+    description="Churn classifier.",
     input_schema=MemberInput,
     output_name="churn_probability",
     output_description="Churn probability 0–1",
@@ -351,11 +397,15 @@ See [`examples/03_orlando_real_estate.py`](examples/03_orlando_real_estate.py) f
 
 Planned for later releases:
 
-- HuggingFace / PyTorch / TensorFlow support
-- Async invocation
-- Weighted ensemble strategies
-- CLI (`predikit inspect model.pkl`)
+- HuggingFace / PyTorch / TensorFlow model support
+- Streaming inference support
+- OpenAI Assistants API integration
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and PR guidelines. The [CHANGELOG](CHANGELOG.md) tracks notable changes per release.
 
 ## License
 
 MIT © Tejas Tumakuru Ashok
+