pashudhan-ai 0.3.0

Official Python SDK for the Pashudhan Nutri AI API

Pashudhan Nutri AI — Official Python SDK

The official Python client library for the Pashudhan Nutri AI API.

This SDK provides a clean, typed interface to generate ICAR-2013+NASEM 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

pip install pashudhan_ai

Quickstart

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")

# 6. Access Advanced Metabolic Analysis (Pro/ProMax plans)
if result.metabolic_report:
    methane = result.metabolic_report.methane
    if methane and methane.applicable:
        print(f"Methane Emission: {methane.enteric_ch4_g_day} g/day")

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:

[
    {
        "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.

Biological Constraints & Validations

The API enforces strict biological validations to prevent unrealistic or harmful rations from being calculated. These limits are deliberately wide enough to cover large dairy breeds (like US Holsteins) as well as buffaloes (which have longer gestations and slower maturation rates).

If your inputs exceed these limits, the API will return a 400 ValidationError (which the SDK catches as pashudhan_ai.exceptions.ValidationError):

• body_weight_kg: Must be between 10 kg and 1500 kg.
• milk_yield_kg_day: Maximum 100 kg/day.
• fat_pct: Must be between 0.5% and 15.0%.
• days_pregnant: Maximum 320 days (accommodates Buffalo gestation limits).
• dim (Days in Milk): Maximum 1000 days.
• Age Mismatches:
  • Calves cannot be older than 18 months.
  • Heifers cannot be older than 48 months.
  • Total age cannot exceed 360 months (30 years).

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:

• ICAR-2013+NASEM 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.