DEV Community

Cover image for 🧠Veterinary AI Workflow with OrKa: Specialist Orchestration, Structured JSON Input, and Observable Reasoning
Mak Sò
Mak Sò

Posted on

🧠Veterinary AI Workflow with OrKa: Specialist Orchestration, Structured JSON Input, and Observable Reasoning

#ai #rag #opensource #programming

Introduction

Modern veterinary medicine often deals with complex clinical cases that require collaboration among multiple specialists, analysis of heterogeneous data, and the production of clear, personalized action plans. In this context, orchestrating AI agents is a promising solution-provided that data is managed in a structured, transparent, and traceable way.

In this article, we’ll explore in depth an advanced veterinary AI workflow based on OrKa, leveraging structured JSON input to orchestrate virtual specialists, integrate diagnoses, and generate personalized action plans. Special attention will be given to observability and traceability of each execution, thanks to detailed reasoning and structured outputs.

1. The Context: AI Orchestration in Veterinary Medicine

1.1. The Complexity of Clinical Cases

A veterinary clinical case can involve multiple symptoms, a detailed clinical history, diagnostic test results, living environment, and owner concerns. Effectively managing this data is essential for accurate diagnosis and effective therapeutic planning.

1.2. The Role of AI Orchestration

An AI orchestrator like OrKa enables you to:

  • Coordinate multiple specialist agents (internal medicine, surgery, infectious diseases, dermatology, etc.)
  • Propagate structured data between agents, avoiding information loss
  • Generate detailed, traceable reasoning for every decision
  • Produce structured outputs, easily reviewable and validatable

2. The Clinical Case: Structured Data as a Starting Point

2.1. Representing the Case in JSON

Let’s imagine managing a case of acute lameness in a dog. The clinical data is collected in a JSON file, faithfully representing the case’s complexity:

{
  "species": "Canine",
  "breed": "Border Collie",
  "age": 2,
  "sex": "Male",
  "weight_kg": 18.3,
  "presenting_complaint": "Acute lameness",
  "symptoms": [
    {"name": "Lameness", "onset": "2 days ago", "severity": "severe", "progression": "sudden"},
    {"name": "Joint swelling", "onset": "2 days ago", "severity": "moderate", "progression": "acute"}
  ],
  "history": {
    "chronic_diseases": [],
    "allergies": [],
    "previous_treatments": [],
    "vaccination_status": "Up to date",
    "recent_travel": false,
    "contact_with_other_animals": true
  },
  "environment": {
    "living": "Outdoor mostly",
    "diet": "Commercial dry food",
    "exposures": ["Fields", "Other dogs"]
  },
  "owner_concerns": "Dog is reluctant to walk.",
  "test_results": {
    "cbc": "Mild neutrophilia",
    "biochemistry": "Normal",
    "radiographs": "Osteolytic lesion on femur",
    "joint_fluid_analysis": "Inflammatory, no bacteria"
  }
}
Enter fullscreen mode Exit fullscreen mode

3. Orchestration: Virtual Specialists in Synergy

The OrKa YAML workflow allows you to orchestrate several AI “specialists,” each focused on a specific aspect of the case. Each agent accesses structured data directly via Jinja2 templates, for example:

prompt: |
  Act as a veterinary internal medicine specialist. Focus ONLY on collecting and interpreting the patient's history and clinical signs.
  Patient data: {{ get_input() }}
  Output: HISTORY_SUMMARY: <summary>, KEY_CLINICAL_SIGNS: [<sign1>, <sign2>]
Enter fullscreen mode Exit fullscreen mode

4. Workflow Execution: Detailed and Traceable Reasoning

The workflow is executed via CLI:

orka run examples/workflow_v2_specialist_linear.yaml examples/inputs/input_case_15.json
Enter fullscreen mode Exit fullscreen mode

Each agent produces detailed reasoning, which is propagated and tracked throughout the workflow. Intermediate and final reasoning are saved and reviewable, ensuring observability and auditability.

5. Observable Reasoning: Real Output Example

Here is a concrete example of a final reasoning, generated by the OrKa veterinary AI workflow, showing the depth, traceability, and actionability of the output:

diagnosis: 'Osteosarcoma of the distal femur - a malignant bone tumour presenting as an osteolytic lesion with acute lameness, joint swelling, mild neutrophilia, and inflammatory joint fluid. The imaging and laboratory findings are highly suggestive of a primary bone malignancy rather than a simple inflammatory process. Osteosarcoma is the most common malignant bone tumour in young, athletic breeds such as Border Collies and often presents with sudden, severe lameness and a lytic lesion on radiographs.'

differentials:
  - Osteomyelitis
  - Benign bone cyst (e.g., simple bone cyst, aneurysmal bone cyst)

specialist_reasoning: 'Orthopedics: The radiographic appearance of a well-defined osteolytic area with periosteal reaction strongly points to a neoplastic process; a biopsy is essential for definitive diagnosis. Oncology: Osteosarcoma prognosis depends on early detection and surgical removal; staging with CT/MRI is recommended if confirmed. Internal Medicine: Mild neutrophilia and inflammatory joint fluid suggest a possible infectious or inflammatory component, but lack of bacteria on culture reduces the likelihood of osteomyelitis. Preventive Medicine: Outdoor exposure and contact with other dogs increase risk of vector-borne infections, which should be ruled out. Veterinary Nutrition: Adequate protein and omega-3 fatty acids support healing and reduce inflammation.'

action_plan: |-
  1. **Immediate Pain Control (Vet)**
     - Carprofen 4.4 mg/kg PO q24h (max 4.4 mg/kg) for 4-6 weeks, tapering as pain improves.
     - Tramadol 1-2 mg/kg PO q8-12h PRN for breakthrough pain.
     - Gabapentin 10 mg/kg PO q12h for neuropathic component.
     - Subcutaneous 0.9 % NaCl 5-10 mL/kg if dehydration noted.
  2. **Diagnostic Confirmation (Vet)**
     - Core needle biopsy of the femoral lesion under sterile conditions; send for histopathology, cytology, and culture.     
     - If joint fluid culture remains negative, perform a repeat culture if clinical suspicion persists.
  3. **Owner Instructions (Owner)**
     - Strict activity restriction: no running, jumping, or prolonged walking; use a sling or padded crate for support.       
     - Monitor temperature, appetite, and lameness daily; call clinic if fever >39.5 °C, swelling increases, or pain worsens. 
     - Provide a high-protein, moderate-fat diet; consider omega-3 supplements (e.g., fish oil 200-300 mg/kg/day).
     - Keep a log of daily temperature, appetite, and a 0-10 lameness score.
  4. **Follow-Up (Vet)**
     - Re-evaluate in 3 days: physical exam, lameness assessment, CBC, biochemistry.
     - If biopsy confirms osteosarcoma: refer to veterinary oncologist for staging (CT/MRI, bone scan) and discuss amputation or limb-sparing surgery.
     - If biopsy indicates osteomyelitis: initiate Amoxicillin-Clavulanate 12.5 mg/kg PO q12h for 10-14 days; adjust per culture results.
  5. **Long-Term Management (Vet & Owner)**
     - Continue NSAID for the full course unless contraindicated; taper gradually.
     - Consider a short course of low-dose prednisone (0.5 mg/kg PO q24h) if severe inflammation persists and infection is ruled out.
     - Schedule imaging (radiographs or CT) every 4-6 weeks to monitor lesion progression.
     - Post-amputation: provide analgesia, wound care, and physiotherapy.
     - If non-surgical, discuss palliative options (radiation, chemotherapy) and quality-of-life measures.
  6. **Additional Considerations**
     - Maintain up-to-date vaccinations and routine preventive care.
     - Use flea/tick prevention to reduce vector-borne disease risk.
     - Seek emergency care if systemic signs (lethargy, vomiting, collapse) appear.

owner_instructions: |-
  1. **Activity**: Keep your dog confined to a small area; avoid stairs and rough terrain.
  2. **Pain Monitoring**: Check for vocalization, reluctance to move, or changes in gait; report immediately.
  3. **Temperature**: Use a rectal thermometer; any reading >39.5 °C warrants a clinic visit.
  4. **Diet**: Feed the recommended portion of the commercial dry food; add a small amount of fish oil if advised.
  5. **Log**: Record daily temperature, appetite, water intake, and a lameness score (0 = normal, 10 = severe). Bring this log to each appointment.
  6. **Follow-Up**: Attend all scheduled visits; bring any new or worsening signs to the clinic promptly.
  7. **Emergency**: If your dog shows sudden collapse, severe pain, or signs of systemic illness, go to an emergency clinic immediately.
Enter fullscreen mode Exit fullscreen mode

6. Observability and Traceability: Every Decision is Transparent

OrKa produces detailed logs for every execution, including:

  • Generated prompts: each agent receives a prompt that includes structured data and previous agent responses.
  • Intermediate outputs: every reasoning produced by agents is saved and can be reviewed later.
  • Decision tracking: it’s possible to reconstruct the entire decision path, from initial data to final diagnosis.

Each execution is tracked with a Trace ID; intermediate reasoning and final outputs are accessible for audit, training, or continuous improvement.

7. Conclusion: Transparent, Traceable, and Robust AI Orchestration

Adopting structured JSON input and observable reasoning in OrKa allows you to:

  • Manage complex clinical cases with rich, structured data.
  • Orchestrate virtual specialists in a transparent and traceable way.
  • Produce detailed reasoning for every decision, facilitating audit, training, and continuous improvement.
  • Generate actionable, validatable outputs, ready for clinical use or integration with other systems.

Announcement: OrKa Reasoning 0.9.9

All this is now possible thanks to the new version of OrKa Reasoning (0.9.9), which introduces:

  • Official support for structured JSON input
  • Robust parsing and advanced error handling
  • Detailed logs and traceable reasoning
  • Validatable and actionable YAML output

Learn more at OrKa Core on GitHub and start experimenting with your own structured workflows!

Top comments (0)