Metadata-Version: 2.1
Name: pashudhan-ai
Version: 0.1.12
Summary: Official Python SDK for the Pashudhan Nutri AI API
Home-page: https://pashudhan-nutri-ai.web.app/enterprise
Author: Pashudhan Nutri AI
Author-email: api@pashudhan.ai
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0

# Pashudhan Nutri AI — Official Python SDK

The official Python client library for the [Pashudhan Nutri AI API](https://pashudhan-nutri-ai.web.app/enterprise).

This SDK provides a clean, typed interface to generate NASEM 2021 compliant dairy rations using our proprietary Optimization and AI Critique engines. **Zero formulation logic is exposed** — all equations, ingredient databases, rule evaluations, and AI models run securely in the cloud. You simply supply the animal profile and available feeds, and we return the optimized diets complete with actionable veterinary insights.

## Installation

```bash
pip install pashudhan_ai
```

## Quickstart

```python
import pashudhan_ai

# Initialize the client with your API key
client = pashudhan_ai.Client(api_key="pd_your_api_key_here")

# 1. Fetch available ingredients for a specific country
# This dynamically loads the available ingredient master list (e.g., India vs USA)
db = client.get_ingredients_list(country="India")
print(f"Loaded {db['total']} ingredients from DB.")

# 2. Define the exact ingredients you want the solver to use
# Pass the IDs. You can optionally override prices, inclusion limits, or lab analysis on the fly.
custom_ingredients = [
    {"id": "wheat_straw"}, 
    {"id": "maize_silage", "price_local_kg_fresh": 1.4}, # Override dynamic local price
    {"id": "maize_grain"},
    {"id": "wheat_bran", "max_inclusion_pct_DM": 15},    # Restrict to max 15% DM
    {"id": "mustard_cake"},
    {"id": "guar_korma"}
]

# 3. Generate a ration
result = client.formulate(
    # --- Animal Profile ---
    animal_type="buffalo",
    breed="Murrah",
    body_weight_kg=500,
    milk_yield_kg_day=12.0,
    fat_pct=7.0,
    production_stage="early_lactation",
    
    # --- Geography & Environment ---
    country="India",
    state="Haryana",
    month=6,
    
    # --- Feed Inventory ---
    available_ingredients=custom_ingredients
)

# 4. Access the generated formulations
least_cost = result.formulations[0]
print(f"Total Cost: {least_cost.total_cost_local_day}/day")

# 5. Access the AI Veterinary Critique
print(f"AI Veterinary Review:\n{least_cost.formulation.ai_explanation}")
for warning in least_cost.formulation.ai_warnings:
    print(f"WARNING: {warning}")

for ingredient in least_cost.formulation.ingredients:
    print(f"{ingredient.name}: {ingredient.kg_fresh_day} kg")
```

## Configuration Guide

The core design of the API is interface-first. You do not need to calculate Dry Matter Intake, energy limits, or NDF minimums. You simply pass the real-world conditions.

### Available Ingredients Payload
To control what feeds the engine uses, pass an array to `available_ingredients`. You can pass just the `id` (which inherits all nutritional data automatically), or you can override specific attributes on the fly:

```python
[
    {
        "id": "soybean_meal", 
        "price_local_kg_fresh": 45.0,  # Specify your own price based on the user's local currency
        "dm_pct": 89.0,                # Override dry matter %
        "CP_pct_DM": 48.0              # Override crude protein % based on your custom lab test
    }
]
```

### Supported API Parameters

**Animal Parameters:**
- `animal_type`: `"cow"`, `"buffalo"`, `"goat"`
- `breed`: e.g. `"HF_crossbred"`, `"Jersey"`, `"Murrah"`, `"Gir"`
- `body_weight_kg`: Float (e.g. 450)
- `milk_yield_kg_day`: Float (e.g. 15.5)
- `fat_pct`: Float (e.g. 4.0)
- `production_stage`: `"early_lactation"`, `"mid_lactation"`, `"dry"`, `"heifer"`, etc.

**Environmental Parameters:**
- `country`: Determines the currency, available database, and base feed parameters (e.g., `"India"`, `"USA"`).
- `location` or `state`: Used to fetch live ambient temperature and humidity to adjust rations for heat stress (THI).
- `month`: Used to apply seasonal rules and local market pricing logic.

## The AI Veterinary Critique Layer
One of the most powerful features of the Pashudhan SDK is the **AI Critique Layer**. 

After the mathematical optimization engine finishes calculating the required nutrients, the AI layer scans the formulation for real-world biological risks that traditional mathematics miss. 

The API returns:
1. `ai_explanation`: A farmer-friendly paragraph explaining the tradeoffs between the different formulation options (Least Cost, Best Biological, Compromise).
2. `ai_warnings`: Specific, actionable alerts if the diet has hidden dangers (e.g., "DANGEROUS Ca:P RATIO", "HIGH ACIDITY RISK due to heavy wheat grain"). 

These intelligent insights allow you to provide your users with veterinary-grade advice directly in your UI, without needing to code complex biological rule engines yourself.

## Security & IP Protection
By using the SDK, your proprietary user data is abstracted from the heavy mathematical lifting. The API securely handles:
- **NASEM 2021 & ICAR 2013 Nutrient Equations**
- **Non-Linear Rumen Kinetics**
- **Veterinary Safety Thresholds**
- **Generative AI Diagnostics**

None of this logic is exposed to or required by the client SDK, making it extremely lightweight and secure for developers to integrate.

## Documentation
For full API reference, visit the [Developer Portal](https://pashudhan-nutri-ai.web.app/enterprise).
