API Query Format

QueryRequest

Request format for the AI agent to search for parts.

Structure:

{
  "query": "string",
  "include_store_link": false
}

Fields:

query (string, required):
- User query text
- Examples:
  - "Find part 10"
  - "What is part number 123?"
  - "Show me hydraulic filter parts"
include_store_link (boolean, optional, default: false):
- Whether to include store link in response
- false: Agent will ask if link is needed
- true: Agent will immediately add store link

Endpoints

POST `/api/ai/query`

Main endpoint for querying the AI agent.

Request:

{
  "query": "Find part 10",
  "include_store_link": false
}

Response:

{
  "answer": "Part 10 is a hydraulic filter. It can be found in schemas F5-540_main and F5-540_hydraulic. Quantity: 1.",
  "parts": [
    {
      "part_number": "10",
      "description": "Hydraulic filter",
      "schemas": ["F5-540_main", "F5-540_hydraulic"],
      "quantity": 1,
      "pdf_link": "https://storage.googleapis.com/crop-documents/mchale/f5-540/F5-540-F5-540C.pdf#page=6",
      "available_for_purchase": true,
      "in_stock": true,
      "stock_quantity": 5,
      "price": 45.99,
      "estimated_delivery": "2-3 business days"
    }
  ],
  "needs_confirmation": false,
  "store_link_question": null
}

POST `/query`

Alias for /api/ai/query (for compatibility).

GET `/test-chat`

Test endpoint to verify chat functionality and model configuration.

Response:

{
  "status": "success",
  "model_config": {
    "api_url": "http://llama-server:8080",
    "model_name": "llama-3.1-8b-instruct",
    "temperature": 0.7,
    "max_tokens": 1000,
    "provider": "llamacpp"
  },
  "test_query": "Hello! Can you tell me who you are and what model you are using?",
  "agent_response": "I am the McHale Vendor Agent Specialist...",
  "agent_state": {
    "parts_found": 0,
    "needs_confirmation": false
  }
}

Response Format

PartResponse

{
  "part_number": "string",
  "description": "string",
  "schemas": ["string"],
  "quantity": 0,
  "pdf_link": "string",
  "available_for_purchase": true,
  "in_stock": true,
  "stock_quantity": 0,
  "price": 0.0,
  "estimated_delivery": "string"
}

Fields:

part_number: Part number (e.g., "10", "CFA00137")
description: Part description
schemas: List of schemas where part is found
quantity: Quantity needed
pdf_link: Link to PDF with page number
available_for_purchase: Whether part is available for purchase
in_stock: Whether part is in stock
stock_quantity: Current stock quantity
price: Part price
estimated_delivery: Estimated delivery time

Examples

Example 1: Simple Query

Request:

{
  "query": "Find part 10"
}

Response:

{
  "answer": "Part 10 is a hydraulic filter...",
  "parts": [...],
  "needs_confirmation": false
}

Example 2: Query with Store Link

Request:

{
  "query": "Find part 10",
  "include_store_link": true
}

Response:

{
  "answer": "Part 10 is a hydraulic filter...",
  "parts": [
    {
      "part_number": "10",
      "store_link": "https://clintontractor.net/parts/productpage/10",
      ...
    }
  ],
  "needs_confirmation": false
}

Example 3: Agent Asks for Confirmation

Request:

{
  "query": "Find part 10",
  "include_store_link": false
}

Response:

{
  "answer": "I found part 10. Would you like a link to the online store?",
  "parts": [...],
  "needs_confirmation": true,
  "store_link_question": "Would you like a link to clintontractor.net/parts/productpage/10?"
}

Error Responses

400 Bad Request

{
  "detail": "query field is required"
}

500 Internal Server Error

{
  "detail": "Error message"
}

Notes

All queries are processed by the AI agent with access to:
- RAG system (Weaviate vector database)
- Elasticsearch (detailed part information)
- MongoDB (additional part data)
- Store API (real-time availability and pricing)
The agent acts as a "McHale Vendor Agent Specialist" with expertise in parts lookup and purchasing consultation.
Store links are only provided when:
- include_store_link: true is set, OR
- User confirms they want the link (when needs_confirmation: true)

API Query Format

On this page