Cooper AI

Cooper is CattleOS's AI assistant that helps farmers manage their operations through natural language. Rather than navigating forms and menus, farmers can simply tell Cooper what they need — "add 50 Angus steers to the North Pen" or "how many cattle are sick?" — and Cooper executes the action or queries the data directly.

Cooper is powered by OpenAI's GPT-4o model with real-time access to 100+ platform tools. When you call the Cooper API, the model decides which tools to invoke, executes them server-side against your farm's data, and returns a natural language summary along with the raw tool results.

Cooper is stateless per request — you maintain conversation history client-side and pass it with each call for multi-turn conversations.

Request Flow

Client Request
     │
     ▼
┌─────────────────────────────────────────────────┐
│  POST /api/v1/cooper/chat                       │
│  Authentication: API Key (cos_live_xxx)         │
│  Scope required: cooper:chat                    │
└─────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────┐
│  System Prompt + User Messages                  │
│  ──────────────────────────────                 │
│  Sent to OpenAI GPT-4o with 100+ tool defs     │
└─────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────┐
│  Tool Execution Loop (up to N rounds)           │
│  ──────────────────────────────────             │
│  1. Model returns tool_calls                    │
│  2. Server executes each tool against your DB   │
│  3. Results fed back to model                   │
│  4. Repeat until model has final answer         │
└─────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────┐
│  JSON Response                                  │
│  ──────────────                                 │
│  { message, tool_calls[], model, usage }        │
└─────────────────────────────────────────────────┘

Two-Tier Model Strategy (Internal)

Within the CattleOS app, Cooper uses a two-tier model approach for optimal speed and quality:

• GPT-4o-mini for tool-routing turns — fast, cheap, and accurate at choosing which tool to call and extracting parameters from natural language
• GPT-4o for the final synthesis turn — composes the user-facing natural language answer from tool results

Via the API, you can choose which model handles the entire flow (both routing and synthesis) using the model parameter.

Tool Execution

Tools execute server-side through the same data layer that powers the REST API. Each tool:

1. Has a Zod schema that validates the model's arguments (same schemas as the HTTP endpoints)
2. Resolves the user's farm context from the API key
3. Calls the data layer directly (no HTTP self-loop)
4. Returns a structured result that's fed back to the model

Large Result Handling

When a tool returns large datasets (e.g. listing 2000+ cattle), the results are automatically compacted before being fed back to the model — truncated to 25 items with a count of total matches. This prevents context window overflow while still giving the model accurate aggregate information. If more detail is needed, the model can re-call with more specific filters.

Cooper's behavior is defined by its system prompt. The API uses a focused, tool-oriented prompt:

You are Cooper, the AI assistant for CattleOS — a cattle management platform.

You have access to real platform tools via function calling. Use them to answer
questions and perform actions on the user's farm data.

Rules:
- For ANY question about farm data (cattle counts, pen info, activities),
  CALL the matching tool.
- For ANY write action (add, create, update, delete, move),
  CALL the matching tool.
- DO NOT answer data questions from memory — always call a tool.
- After tools return, respond in natural language summarizing what happened.
- Be conversational and helpful. If you need more information before acting, ask.
- When adding cattle, ALWAYS ask for a tag number — never auto-generate one.
- For inventory, always require name and quantity.

The internal app version (used in the CattleOS UI) includes additional context like the user's identity, team roster, and detailed interaction examples — but the core philosophy is the same: always use tools for data, never guess.

Cooper has access to the full CattleOS platform through OpenAI function calling. Tools are defined using Zod schemas that match the REST API — ensuring the AI can do exactly what the UI can do, no more, no less.

Endpoint

Headers

Authorization: Bearer cos_live_your_key_here
Content-Type: application/json

Request Body

Response Body

{
  "data": {
    "message": "You have 2,353 cattle. 847 are in the North Pen, 1,206 in South Pen...",
    "tool_calls": [
      {
        "name": "list_cattle",
        "arguments": {},
        "result": {
          "matchingCount": 2353,
          "items": [...]
        }
      }
    ],
    "model": "gpt-4o",
    "usage": {
      "prompt_tokens": 1850,
      "completion_tokens": 67,
      "total_tokens": 1917
    }
  }
}

Response Fields

• Voice assistants — Pipe speech-to-text output into Cooper for hands-free farm management while working in the field
• Chatbots — Embed Cooper in WhatsApp, Telegram, or SMS for farmers who prefer messaging
• Automated reporting — Schedule daily queries ("Give me a summary of today's activities") and email the results
• IoT integration — When a scale reads a weight, send "Record weight 847 lbs for tag 234" to automatically log it
• Mobile apps — Build custom farm management UIs that use Cooper as the backend intelligence
• Slack/Teams bots — Let your team query farm data from their existing chat tools