predikit 0.1.0__py3-none-any.whl

predikit/__init__.py

@@ -0,0 +1,5 @@
+from .tool import ModelTool
+from .registry import ToolRegistry
+
+__all__ = ["ModelTool", "ToolRegistry"]
+__version__ = "0.1.0"

predikit/coerce.py

@@ -0,0 +1,50 @@
+from typing import Any
+from pydantic import BaseModel
+
+
+_BOOL_TRUE = {"true", "1", "yes", "on"}
+_BOOL_FALSE = {"false", "0", "no", "off"}
+
+
+def coerce_value(value: Any, target_type: type) -> Any:
+    """Coerce a single value to target_type with LLM-friendly string handling."""
+    if isinstance(value, target_type):
+        return value
+
+    if target_type is bool:
+        if isinstance(value, str):
+            low = value.lower()
+            if low in _BOOL_TRUE:
+                return True
+            if low in _BOOL_FALSE:
+                return False
+            raise ValueError(f"Cannot interpret {value!r} as bool. Expected one of: true/false, yes/no, 1/0, on/off")
+        return bool(value)
+
+    if target_type is int:
+        return int(float(value))
+
+    if target_type is float:
+        return float(value)
+
+    if target_type is str:
+        return str(value)
+
+    return value
+
+
+def coerce_inputs(validated: BaseModel, meta: dict) -> list:
+    """Return feature values in the order the model expects them."""
+    data = validated.model_dump()
+    feature_names = meta.get("feature_names")
+    if feature_names:
+        missing = [f for f in feature_names if f not in data]
+        if missing:
+            raise ValueError(
+                f"Input schema is missing model features: {missing}. "
+                f"Field names in your Pydantic schema must exactly match the column names "
+                f"used during model training. "
+                f"Schema has: {list(data.keys())}, model expects: {feature_names}"
+            )
+        return [data[f] for f in feature_names]
+    return list(data.values())

predikit/exporters/langchain.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..tool import ModelTool
+
+
+def to_langchain_tool(tool: ModelTool):
+    """Convert a ModelTool to a LangChain StructuredTool."""
+    try:
+        from langchain_core.tools import StructuredTool
+    except ImportError:
+        raise ImportError(
+            "langchain-core is required. Install with: pip install predikit[langchain]"
+        )
+
+    def _run(**kwargs) -> dict:
+        return tool.invoke(kwargs)
+
+    return StructuredTool.from_function(
+        func=_run,
+        name=tool.name,
+        description=tool.description,
+        args_schema=tool.input_schema,
+    )

predikit/exporters/openai.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..tool import ModelTool
+
+
+def to_openai_schema(tool: ModelTool) -> dict:
+    """Convert a ModelTool to an OpenAI function-calling schema dict."""
+    schema = tool.input_schema.model_json_schema()
+    schema.pop("title", None)
+
+    return {
+        "type": "function",
+        "function": {
+            "name": tool.name,
+            "description": tool.description,
+            "parameters": schema,
+        },
+    }

predikit/introspect.py

@@ -0,0 +1,22 @@
+from typing import Any
+
+
+def introspect(model: Any) -> dict:
+    """Extract metadata from a fitted sklearn-compatible estimator."""
+    meta: dict = {}
+
+    meta["feature_names"] = (
+        list(model.feature_names_in_) if hasattr(model, "feature_names_in_") else None
+    )
+    meta["n_features"] = (
+        int(model.n_features_in_) if hasattr(model, "n_features_in_") else None
+    )
+
+    if hasattr(model, "classes_"):
+        meta["task"] = "classification"
+        meta["classes"] = list(model.classes_)
+    else:
+        meta["task"] = "regression"
+        meta["classes"] = None
+
+    return meta

predikit/registry.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+from .tool import ModelTool
+
+
+class ToolRegistry:
+    """Bundles multiple ModelTools and provides bulk export methods."""
+
+    def __init__(self, tools: list[ModelTool]) -> None:
+        self._tools: dict[str, ModelTool] = {t.name: t for t in tools}
+
+    def get(self, name: str) -> ModelTool:
+        if name not in self._tools:
+            raise KeyError(f"No tool named '{name}'. Available: {list(self._tools)}")
+        return self._tools[name]
+
+    def to_openai(self) -> list[dict]:
+        return [t.to_openai() for t in self._tools.values()]
+
+    def to_langchain(self) -> list:
+        return [t.to_langchain() for t in self._tools.values()]

predikit/tool.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+from typing import Any, Callable
+
+import numpy as np
+from pydantic import BaseModel
+
+from .introspect import introspect
+from .coerce import coerce_inputs, coerce_value
+from .exporters.openai import to_openai_schema
+from .exporters.langchain import to_langchain_tool
+
+# Only apply pre-coercion for these scalar types; everything else goes straight to Pydantic.
+_SCALAR_TYPES = (bool, int, float, str)
+
+
+class ModelTool:
+    """Wraps a fitted sklearn-compatible model as an LLM-callable tool."""
+
+    def __init__(
+        self,
+        model: Any,
+        name: str,
+        description: str,
+        input_schema: type[BaseModel],
+        output_name: str,
+        output_description: str,
+    ) -> None:
+        self.model = model
+        self.name = name
+        self.description = description
+        self.input_schema = input_schema
+        self.output_name = output_name
+        self.output_description = output_description
+        self._meta = introspect(model)
+
+    def invoke(self, input_dict: dict) -> dict:
+        """Validate inputs, run prediction, return {output_name: value}."""
+        pre_coerced = self._pre_coerce(input_dict)
+        try:
+            validated = self.input_schema(**pre_coerced)
+        except Exception as exc:
+            raise ValueError(f"Input validation failed for '{self.name}': {exc}") from exc
+
+        features = coerce_inputs(validated, self._meta)
+        X = self._to_array(features)
+        prediction = self.model.predict(X)[0]
+
+        if hasattr(prediction, "item"):
+            prediction = prediction.item()
+
+        return {self.output_name: prediction}
+
+    def to_openai(self) -> dict:
+        """Return an OpenAI function-calling schema dict."""
+        return to_openai_schema(self)
+
+    def to_langchain(self):
+        """Return a LangChain StructuredTool."""
+        return to_langchain_tool(self)
+
+    def to_callable(self) -> Callable[..., dict]:
+        """Return a plain Python function that calls invoke()."""
+        def _fn(**kwargs) -> dict:
+            return self.invoke(kwargs)
+        _fn.__name__ = self.name
+        _fn.__doc__ = self.description
+        return _fn
+
+    def _pre_coerce(self, input_dict: dict) -> dict:
+        # Runs coerce_value before Pydantic so LLM strings like "yes"/"no" work for bool fields.
+        fields = self.input_schema.model_fields
+        result = {}
+        for k, v in input_dict.items():
+            field = fields.get(k)
+            annotation = getattr(field, "annotation", None) if field else None
+            if annotation in _SCALAR_TYPES:
+                try:
+                    result[k] = coerce_value(v, annotation)
+                except (ValueError, TypeError):
+                    result[k] = v  # let Pydantic surface the error with full context
+            else:
+                result[k] = v
+        return result
+
+    def _to_array(self, features: list) -> Any:
+        feature_names = self._meta.get("feature_names")
+        if feature_names:
+            try:
+                import pandas as pd
+                return pd.DataFrame([dict(zip(feature_names, features))])
+            except ImportError:
+                pass
+        return np.array([features])

predikit-0.1.0.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: predikit
+Version: 0.1.0
+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
+Author-email: Tejas Tumakuru Ashok <tejas.tumakuruashok@travelandleisure.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,function-calling,llm,ml-tools,sklearn,xgboost
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pydantic>=2.0
+Requires-Dist: scikit-learn>=1.2
+Provides-Extra: dev
+Requires-Dist: langchain-core>=0.1; extra == 'dev'
+Requires-Dist: pandas>=1.5; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: xgboost>=1.7; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1; extra == 'langchain'
+Provides-Extra: xgboost
+Requires-Dist: xgboost>=1.7; extra == 'xgboost'
+Description-Content-Type: text/markdown
+
+# predikit
+
+Turn any trained scikit-learn or XGBoost model into an LLM-callable tool — auto-generated JSON schemas, typed I/O, zero boilerplate.
+
+```python
+tool = ModelTool(model=clf, name="classify_iris", ...)
+tool.to_openai()              # OpenAI function schema, ready to pass to the API
+tool.invoke({"sqft": 2200})   # → {"price_usd": 370730}
+```
+
+## Install
+
+```bash
+pip install predikit
+
+# With XGBoost support
+pip install predikit[xgboost]
+
+# With LangChain support
+pip install predikit[langchain]
+```
+
+## 30-second example
+
+```python
+from pydantic import BaseModel, Field
+from sklearn.datasets import load_iris
+from sklearn.linear_model import LogisticRegression
+from predikit import ModelTool
+
+# Train
+X, y = load_iris(return_X_y=True)
+clf = LogisticRegression(max_iter=200).fit(X, y)
+
+# Define what the LLM will pass in
+class IrisInput(BaseModel):
+    sepal_length: float = Field(description="Sepal length in cm")
+    sepal_width:  float = Field(description="Sepal width in cm")
+    petal_length: float = Field(description="Petal length in cm")
+    petal_width:  float = Field(description="Petal width in cm")
+
+# Wrap the model
+tool = ModelTool(
+    model=clf,
+    name="classify_iris",
+    description="Classify an iris flower: 0=setosa, 1=versicolor, 2=virginica.",
+    input_schema=IrisInput,
+    output_name="species",
+    output_description="Predicted species index",
+)
+
+# Get an OpenAI-ready schema
+import json
+print(json.dumps(tool.to_openai(), indent=2))
+
+# Call it directly
+tool.invoke({
+    "sepal_length": 5.1, "sepal_width": 3.5,
+    "petal_length": 1.4, "petal_width": 0.2,
+})
+# → {"species": 0}
+```
+
+## Core API
+
+### `ModelTool`
+
+```python
+ModelTool(
+    model,               # fitted sklearn-compatible estimator
+    name: str,           # tool name the LLM sees
+    description: str,    # tool description the LLM sees
+    input_schema,        # Pydantic BaseModel describing inputs
+    output_name: str,    # key for the prediction in the returned dict
+    output_description: str,
+)
+```
+
+| Method | Returns | What it does |
+|--------|---------|--------------|
+| `.invoke(input_dict)` | `dict` | Validates → predicts → returns `{output_name: value}` |
+| `.to_openai()` | `dict` | OpenAI function-calling schema |
+| `.to_langchain()` | `StructuredTool` | LangChain tool |
+| `.to_callable()` | `Callable` | Plain Python function |
+
+### `ToolRegistry`
+
+Group multiple tools for bulk export:
+
+```python
+registry = ToolRegistry([price_tool, risk_tool])
+registry.to_openai()     # → list[dict], pass directly to OpenAI
+registry.to_langchain()  # → list[StructuredTool]
+registry.get("name")     # → ModelTool
+```
+
+## Field naming rule
+
+**Your Pydantic schema field names must exactly match the column names the model was trained on.**
+
+predikit maps inputs to features by name, not position. If you trained on a DataFrame with columns `["sqft", "bedrooms"]`, your schema fields must be `sqft` and `bedrooms` — not `sq_ft`, not `Sqft`.
+
+```python
+# ✓ Columns match: sqft, bedrooms, bathrooms
+class GoodInput(BaseModel):
+    sqft:      float
+    bedrooms:  float
+    bathrooms: float
+
+# ✗ Name mismatch — raises ValueError at runtime
+class BadInput(BaseModel):
+    square_footage: float  # model expects "sqft"
+    beds:           float  # model expects "bedrooms"
+    baths:          float  # model expects "bathrooms"
+```
+
+When there's a mismatch, predikit tells you exactly which names are wrong:
+
+```
+ValueError: Input schema is missing model features: ['sqft', 'bedrooms'].
+Schema has: ['square_footage', 'beds', 'bathrooms'], model expects: ['sqft', 'bedrooms', 'bathrooms']
+```
+
+> **Tip:** If you trained with a numpy array (no DataFrame), predikit has no feature names to check — it uses your schema's field definition order instead.
+
+## Cookbook
+
+### XGBoost regression
+
+```python
+from xgboost import XGBRegressor
+from predikit import ModelTool
+
+reg = XGBRegressor().fit(X_train, y_train)
+
+class HouseInput(BaseModel):
+    sqft:       float
+    bedrooms:   float
+    year_built: float
+
+tool = ModelTool(
+    model=reg,
+    name="price_estimate",
+    description="Predict home price in USD.",
+    input_schema=HouseInput,
+    output_name="price_usd",
+    output_description="Predicted sale price in USD",
+)
+```
+
+### Multiple tools in one registry
+
+```python
+registry = ToolRegistry([price_tool, risk_tool, demand_tool])
+
+# OpenAI
+response = client.chat.completions.create(
+    model="gpt-4o",
+    tools=registry.to_openai(),
+    ...
+)
+
+# LangChain
+agent = initialize_agent(tools=registry.to_langchain(), ...)
+```
+
+### Bool inputs from an LLM
+
+LLMs sometimes return `"yes"`, `"true"`, or `"1"` for boolean fields. predikit coerces these automatically before Pydantic validation:
+
+```python
+class Input(BaseModel):
+    has_pool: bool
+
+tool.invoke({"has_pool": "yes"})   # → coerced to True
+tool.invoke({"has_pool": "false"}) # → coerced to False
+tool.invoke({"has_pool": "maybe"}) # → raises ValueError with clear message
+```
+
+Supported strings: `true/false`, `yes/no`, `1/0`, `on/off`.
+
+### Orlando real estate demo
+
+See [`examples/03_orlando_real_estate.py`](examples/03_orlando_real_estate.py) for a full end-to-end walkthrough: synthetic dataset → XGBoost training → `ModelTool` → registry → OpenAI schema → prediction.
+
+## Roadmap
+
+Intentionally out of scope for v0.1 — planned for later releases:
+
+- Confidence-aware routing & fallback
+- Multi-model synthesis (agent calls several, reconciles results)
+- MLflow / Snowflake Model Registry integration
+- HuggingFace / PyTorch / TensorFlow support
+- Async invocation
+
+## License
+
+MIT © Tejas Tumakuru Ashok

predikit-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+predikit/__init__.py,sha256=pybtPHFnZV9Q8yyLXA-cCtbZcLL1f_jbERBQboEfZfU,126
+predikit/coerce.py,sha256=Pw0CwSgDBvW0j5zYbQyRd1jX3dr6j9Gcx-FgT91fWuc,1629
+predikit/introspect.py,sha256=0J71ye3YC6y473Uui5rAO58yBVI39jB0y3KKFIlfgIM,606
+predikit/registry.py,sha256=bH3ulINhbzy9y67vsbgo94lNOBvuWmUR8FGzKjx5JJY,686
+predikit/tool.py,sha256=xyV_r65-CfnhmMtRkFbNoBhsgpkzEkXMJTbJlY0UKCc,3224
+predikit/exporters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+predikit/exporters/langchain.py,sha256=2-ut2OT90JuZWK1rZheUtKzaPmK_JwwLYrReNpcmLgY,673
+predikit/exporters/openai.py,sha256=GWaffvb6FFI8tlqI9UlLi-u5n3-YT2ikKvj5UpHrCWA,514
+predikit-0.1.0.dist-info/METADATA,sha256=hedfKoGKoHWBmTLh9tmTTu1-yqYv3KjVGFHP62QJuoQ,7115
+predikit-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+predikit-0.1.0.dist-info/licenses/LICENSE,sha256=wszEW4O1EXHs-UrAlT3-5HEFG78t1QVc4u4jymKPWiI,1077
+predikit-0.1.0.dist-info/RECORD,,

predikit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

predikit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tejas Tumakuru Ashok
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.