Pashudhan Nutri AI API

The Pashudhan Nutri AI API gives your cooperative or agri-tech platform plug-and-play access to India's most accurate dairy ration engine. Send a single HTTP request and receive a complete, science-backed ration in JSON — or use the official pashudhan_ai Python SDK for a one-liner workflow.

Authentication

All API requests require an x-api-key header. Get your key from the API Dashboard. Treat it like a password — never expose it in client-side code.

curl -X POST https://pashudhan-nutri-ai.web.app/api/formulate \
  -H "x-api-key: pd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Quickstart

Get a complete ration in under 60 seconds. Choose your language:

import pashudhan_ai

client = pashudhan_ai.Client(api_key="pd_your_key_here")

result = client.formulate(
    animal_type       = "cow",
    breed             = "HF_crossbred",
    body_weight_kg    = 450,
    milk_yield_kg_day = 18,
    fat_pct           = 3.5,
    production_stage  = "mid_lactation",
    state             = "Punjab",
    month             = 5,
    location          = "30.90,75.85" # Optional: For live THI tracking
)

# Access all 4 optimisation strategies
for opt in result.formulations:
    print(opt.mode, opt.total_cost_local_day)  # e.g. least_cost 248.5

# Or use convenience properties
print(result.least_cost.total_cost_local_day)
for ing in result.least_cost.ingredients:
    print(f"{ing.name}: {ing.kg_fresh_day} kg")

AI Agents & MCP Integration

The Pashudhan Nutri AI platform natively supports the open-source Model Context Protocol (MCP). This means you can instantly give AI assistants the ability to formulate rations, check live heat stress (THI), and query the ICAR-NDRI ingredient database directly within their chat interfaces.

How to connect Claude Desktop

1. Go to your API Dashboard and generate an Enterprise API Key.
2. Click the Download MCP Config button next to your key.
3. This downloads a pashudhan_mcp_config.json file.
4. Copy the contents of this file into your Claude Desktop configuration file.
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
5. Restart Claude Desktop. The AI will now have access to the Pashudhan Formulation Tools!

Python SDK — Install

Install via pip

Requirements

Python >= 3.8
requests >= 2.28

Python SDK — Usage

Initialize the client

import pashudhan_ai

# Option 1: Pass key directly
client = pashudhan_ai.Client(api_key="pd_your_key_here")

# Option 2: Set environment variable PASHUDHAN_API_KEY
client = pashudhan_ai.Client()  # reads from env automatically

Formulate a ration

result = client.formulate(
    animal_type       = "cow",
    breed             = "Sahiwal",
    body_weight_kg    = 380,
    milk_yield_kg_day = 10,
    fat_pct           = 4.2,
    production_stage  = "mid_lactation",
    state             = "Rajasthan",
    month             = 11,
    use_ai            = True,      # enable AI Nutritionist critique
    location          = "Jaipur"   # fetch live weather data
)

# Access all 4 strategies
for opt in result.formulations:
    print(f"[{opt.mode}] Cost: {opt.total_cost_local_day}/day  NEL={opt.nutrients.nel_mcal_kg_dm} Mcal/kg")

# Access AI Explanation
if result.ai_explanation:
    print("AI says:", result.ai_explanation)

# Access Live THI data
if result.thi_report:
    print(f"Live THI: {result.thi_report.thi} ({result.thi_report.category})")

# Access Metabolic Report (Requires Pro/Enterprise Plan)
if result.metabolic_report:
    print(f"Methane: {result.metabolic_report.methane.enteric_ch4_g_day} g/day")
    print(f"RUP/RDP Status: {result.metabolic_report.rup_rdp.ratio_status}")

Check your usage

status = client.status()
print(status.plan)          # "starter" / "pro" / "pro_max"
print(status.calls_used)    # API calls used this month
print(status.calls_limit)   # monthly limit

API Reference

The core endpoint. Returns up to 4 optimized ration strategies in JSON.

Request Body

Response

{
  "request_id": "req_abc123",
  "formulations": [
    {
      "mode": "least_cost",
      "total_cost_local_day": 248.50,
      "feed_cost_local_day": 220.0,
      "formulation": {
        "ingredients": [
          { "name": "Wheat Straw",  "kg_fresh_day": 5.0, "cost_local_day": 22.5 },
          { "name": "Maize Grain",  "kg_fresh_day": 3.5, "cost_local_day": 87.5 }
        ],
        "nutrient_summary": { "NEL_Mcal_day": 22.1, "CP_g_day": 1680, "NDF_pct_DM": 32.4 },
        "ai_explanation": "Option 1 is the cheapest but has severe nutrient gaps. A calcium supplement MUST be added.",
        "ai_warnings": [
          "DANGEROUS Ca:P RATIO: The calcium-to-phosphorus ratio is 0.51 — far below the safe minimum of 1.5:1."
        ]
      },
      "palatability": { "score": 88, "refusal_probability_pct": 8 },
      "adaptive_reasoning": ["Ration is nutritionally balanced. Consider adding bypass fat..."]
    }
  ],
  "thi_report": { "thi": 78, "category": "mild_stress", "adjusted_water_L_day": 82 },
  "metabolic_report": { 
    "methane": { "enteric_CH4_g_day": 345, "CO2e_kg_year": 3524, "vs_benchmark_pct": -4, "mitigation_tips": ["Increase fat"], "applicable": true },
    "rup_rdp": { "ratio_status": "Optimal", "actual_rdp_rup_ratio": "65:35", "applicable": true },
    "amino_acids": { "lys_pct_mp": 6.9, "met_pct_mp": 2.2, "applicable": true }
  }
}

Formulates for an entire herd. Deducts 4 API credits per call.

Request Body

Example Request Body

{
  "state": "Punjab",
  "month": 5,
  "farmer_ingredients": ["Wheat Straw", "Maize Grain"],
  "groups": [
    {
      "category": "Lactating",
      "entries": [
        {
          "animal_type": "cow",
          "breed": "HF_crossbred",
          "count": 10,
          "body_weight_kg": 500,
          "milk_yield_kg_day": 20,
          "milk_fat_pct": 3.5,
          "production_stage": "mid_lactation"
        }
      ]
    }
  ]
}

Example Response

{
  "herd_summary": {
    "total_animals": 10,
    "total_feed_cost_inr": 2485.00,
    "avg_cost_per_animal_inr": 248.50,
    "thi": 78
  },
  "groups": [
    {
      "category": "Lactating",
      "animal_count": 10,
      "total_group_cost_inr": 2485.00,
      "formulation": {
        "strategy": "least_cost",
        "ingredients": [
          { "name": "Wheat Straw", "kg_fresh_day": 50.0, "cost_inr": 225.0 },
          { "name": "Maize Grain", "kg_fresh_day": 35.0, "cost_inr": 875.0 }
        ],
        "nutrients": { "NEL_Mcal_day": 221.0, "CP_g_day": 16800 },
        "ai_explanation": "Group is well-balanced. Monitor heat stress impact on DMI."
      }
    }
  ]
}

Returns all available subscription plans. No authentication required.

curl https://pashudhan-nutri-ai.web.app/api/plans

Returns your current plan and monthly API usage. Requires x-api-key header or Authorization: Bearer <firebase-token>.

curl https://pashudhan-nutri-ai.web.app/api/enterprise/status \
  -H "x-api-key: pd_your_key_here"

# Response:
{
  "plan": "starter",
  "monthly_limit": 1000,
  "requests_used": 142
}

Returns all available ingredients with their composition for a given country. This allows you to build custom ingredient picker UIs. Requires x-api-key. By default, it returns Indian ingredients with INR prices. Passing ?country=USA will return USA ingredients with USD prices.

# India (Default)
curl "https://pashudhan-nutri-ai.web.app/api/ingredients-list?country=India" \
  -H "x-api-key: pd_your_key_here"

# USA
curl "https://pashudhan-nutri-ai.web.app/api/ingredients-list?country=USA" \
  -H "x-api-key: pd_your_key_here"

Returns a list of supported countries and their configurations (currency, regions). No authentication required.

curl https://pashudhan-nutri-ai.web.app/api/countries

Returns the dairy breeds available for a specific country, along with their default body weights and milk fat metrics. No authentication required.

# India (Default)
curl "https://pashudhan-nutri-ai.web.app/api/breeds?country=India"

# USA
curl "https://pashudhan-nutri-ai.web.app/api/breeds?country=USA"

🌿 Feeding Best Practices

The Pashudhan Nutri AI API returns scientifically optimised rations. To help your users get the best real-world outcomes, consider surfacing the following guidance alongside the formulation results.

Total Mixed Ration (TMR) — Prevent Sorting

When feeding a TMR, mix dry roughage with concentrates and wet ingredients (silage, green fodder) thoroughly in the manger or a chaff cutter. Add a small amount of water or molasses to bind fine particles. This prevents dominant animals from sorting out concentrates and consuming excess starch, which causes acidosis and laminitis in high-yielding cows.

Transition Cow Management (21 Days Before Calving)

The transition period is the most critical phase in a dairy cow's production cycle. Follow these rules for close-up dry cows:

• Feed anionic salts (e.g., calcium chloride, ammonium sulphate) to keep DCAD negative (-10 to -15 mEq/100g DM), which prevents milk fever (hypocalcaemia).
• Limit dietary calcium to < 0.5% DM to prime the parathyroid hormone response before calving.
• Avoid over-conditioning — target BCS 3.0–3.25 at calving to reduce risk of fatty liver and ketosis.
• Provide propylene glycol (300 mL/day) as a gluconeogenic precursor for cows with BCS > 3.5 going into the dry period.

Heat Stress Mitigation (THI > 72)

When the Temperature-Humidity Index (THI) exceeds 72, dairy cows can lose 2–4 kg of milk per day. The API's THI response field signals when heat stress is active. Advise your users to:

• Shift feeding times to early morning (5–7 AM) and late evening (7–10 PM) when ambient temperature is lower and DMI is higher.
• Increase bypass fat (e.g., Calcium Soap of Fatty Acids, 200–300 g/day) to compensate for reduced DMI without increasing rumen heat load.
• Ensure continuous access to clean, cool water — heat-stressed cows drink 50% more. Install shade nets over water troughs.
• Add sodium bicarbonate (100–150 g/day) as a rumen buffer — heat stress reduces salivation and ruminal buffering capacity.

🐄 Herd Management Tips

Grouping Strategy

For herd formulation to be most effective, group animals with similar nutritional needs. The following grouping strategy is recommended for semi-intensive farms:

Manger Space & Feeding Frequency

• Provide minimum 60 cm of manger space per cow. Inadequate space is the single biggest cause of low DMI and feed sorting in most farm conditions.
• Feed at least twice daily (morning + evening). For high-yielding cows (>25 L), three feedings significantly improve DMI and milk fat.
• Push up feed every 2–3 hours to encourage eating. Cows eat most actively in the 2 hours after milking.
• Weigh feed refusals daily. Target 3–5% refusal — if refusals are zero, the cow is underfed; if >10%, the ration palatability is low.

Monitoring & Body Condition Score (BCS)

BCS is the most practical on-farm indicator of energy balance. Train your users to score their herd monthly:

🌞 Seasonal Feeding Calendar

Ingredient availability and nutritional value varies significantly by season in India. Use the month field in all API calls — the engine automatically adjusts ingredient prices and availability based on the season for the given state.

🧬 Biological Constraints & Validations

The Pashudhan Nutri API actively guards against biologically impossible inputs to ensure generated formulations remain safe and adhere to ICAR & NASEM standards. All limits are widened appropriately to accommodate the longer gestation and slower maturity of Buffalo breeds.

⚠ Error Codes Reference

The API returns standard HTTP status codes. Always check the detail field in error responses for a human-readable message.