farmos-observations

Query and create field observations and AI-processed captures. Photos, voice notes, and text notes from the field.

# FarmOS Observations

AI-powered quick capture system — field observations, photos, voice notes, and issue reports.

## When to Use This

**What this skill handles:** Field observations -- pest/disease/weed reports, crop condition notes, weather damage, soil issues, equipment problems spotted in the field, and photo-based scouting captures.

**Trigger phrases:** "found [pest/weed/disease] in field X", "beans look rough", "something is wrong with field 12", "create an observation", "log this problem", "any observations today?", "what has been reported in field X?"

**What this does NOT handle:** Equipment maintenance scheduling or fleet status (use farmos-equipment), task/work order creation (use farmos-tasks -- but the bot will offer to create a work order after logging an observation), weather forecasts or spray conditions (use farmos-weather).

**Minimum viable input:** Any mention of something observed in the field. "Beans look bad" is enough -- the bot will ask smart follow-ups.

## Data Completeness

1. **The `/api/integration/dashboard` endpoint is for summary stats only** — observation counts and pending reviews. Do NOT use it to list individual observations.
2. **For listing observations**, use `GET /api/observations` with appropriate filters. This endpoint is paginated — use `limit` parameter and note the total.
3. **Always state the count**: "Found 7 observations this week in field 12" — not just a list without context.
4. **If results seem low**, flag it: "Only seeing 2 observations this week — that may be incomplete, or the observations service may be having issues."
5. **If the service is down**, say so plainly. Don't present empty results as "no observations."

## API Base

http://100.102.77.110:8008

**Note:** The observations backend may have stability issues (restart loops reported). If endpoints don't respond, report that the observations service appears to be down.

## Integration Endpoints (No Auth)

### Dashboard
GET /api/integration/dashboard

Returns: Observation counts, recent activity, pending reviews.

## Authenticated Endpoints (JWT Required)

### Authentication

This skill accesses protected FarmOS endpoints that require a JWT token.

**To get a token:**
```bash
TOKEN=$(~/clawd/scripts/farmos-auth.sh manager)
```

**To use the token:**
```bash
curl -H "Authorization: Bearer $TOKEN" http://100.102.77.110:8008/api/endpoint
```

**Token expiry:** Tokens last 15 minutes. If you get a 401 response, request a new token.

### List Observations
GET /api/observations?limit=10&field_id=12
Authorization: Bearer {token}

### Observation Detail
GET /api/observations/{id}
Authorization: Bearer {token}

Returns: Full observation with AI analysis results, extracted entities, urgency score, and any created actions (tasks, maintenance records).

### Create Observation
POST /api/observations
Authorization: Bearer {token}
Content-Type: multipart/form-data

Form fields:
- `observation_type` (required) — pest, disease, weed, weather_damage, equipment_issue, soil, crop_condition, other
- `description` (required) — Text description of what was observed
- `severity` (optional) — low, medium, high (default: medium)
- `field_id` (optional) — Numeric field ID
- `equipment_id` (optional) — Numeric equipment ID
- `photo` (optional) — Image file attachment

Example using curl:
```bash
curl -X POST http://100.102.77.110:8008/api/observations \
  -H "Authorization: Bearer $TOKEN" \
  -F "observation_type=weed" \
  -F "description=Found waterhemp in northeast corner near waterway" \
  -F "severity=high" \
  -F "field_id=22" \
  -F "photo=@/path/to/photo.jpg"
```

**When crew reports a problem in #field-support or #field-ops, offer to create an observation.** Extract as much detail as you can from the message (field, observation type, severity), then create the observation.

## Usage Notes

- Observations include urgency scores (1-10). Flag anything 7+ immediately.
- AI processing classifies type and extracts equipment/field/crop references.
- Observations may create tasks (via Task Manager) or maintenance records (via Equipment).
- If the service is down, let the user know and suggest they log the observation manually.
- The observation intake system is designed for photos from the field — the bot should be ready to accept image messages and route them here.
- **Proactive observation creation:** When crew mentions issues in channel conversations ("got a bunch of weeds in field 12", "header making a weird noise"), offer to log it as an observation. Don't create silently — ask first.
- **Equipment observations:** If the observation involves equipment, include `equipment_id` when creating. This helps track equipment-specific recurring issues.


---

## Smart Observation Detection

When a user reports something that sounds like a field observation, auto-detect as much as you can from the message before asking questions.

### What to Detect

**Field identification:**
- Explicit: "field 12", "F12", "the 12"
- By name: "the Byrd farm", "Kruckeberg", "home place" -- match to known field names
- From channel context: if the conversation was already about a specific field, carry that forward
- From user location: if they mention "the field I am in" or "out here", check recent context

**Observation type** -- see the Observation Type Detection table below.

**Severity** -- see the Severity Detection table below.

**Specific pest/disease/weed identification:**
- Common Indiana pests: western corn rootworm, Japanese beetle, corn earworm, soybean aphid, bean leaf beetle, armyworm, black cutworm, stink bug
- Common diseases: tar spot, gray leaf spot, northern leaf blight, sudden death syndrome, white mold, frogeye leaf spot, Goss wilt, anthracnose
- Common weeds: waterhemp, marestail (horseweed), giant ragweed, common ragweed, Palmer amaranth, lambsquarters, foxtail, velvetleaf, morningglory
- If the reporter uses a colloquial name, map it: "buttonweed" -> common buttonweed, "volunteer corn" -> note as weed/volunteer

**Equipment reference:**
- By name/number: "the 8250", "the Kinze", "the planter", "sprayer"
- By implication: "header won't raise" implies the combine (likely 8250)

**Location within field:**
- Cardinal directions: "northeast corner", "south end"
- Landmarks: "near the waterway", "along the tree line", "by the road", "headlands", "terrace"
- Coverage: "whole field", "scattered", "in patches", "one spot"

---

## Observation Type Detection

| Keywords / Signals | Observation Type |
|--------------------|-----------------|
| bug, insect, aphid, rootworm, armyworm, beetle, cutworm, earworm, stink bug, larva, grub | pest |
| tar spot, gray leaf spot, northern leaf blight, rust, rot, blight, lesion, spots on leaves, mold, wilt, SDS, anthracnose, frogeye | disease |
| waterhemp, marestail, ragweed, foxtail, lambsquarters, Palmer, volunteer corn, weeds, escapes, resistance | weed |
| hail, wind damage, flood, frost, drought stress, storm, ice, lightning, washout, ponding | weather_damage |
| broken, leaking, stuck, noise, won't start, overheating, vibration, warning light, hydraulic, flat tire | equipment_issue |
| compaction, erosion, drainage, wet spots, tile, washout, ruts, soil test, pH | soil |
| stand count, emergence, color, lodging, population, uneven, stunted, yellowing, purpling, canopy | crop_condition |

**If multiple types match** (e.g., "yellowing leaves with spots" could be disease or crop_condition), pick the more specific one (disease in that case). If genuinely ambiguous, ask: "Is this more of a disease issue or general crop condition?"

---

## Severity Detection

| Language Signals | Severity |
|-----------------|----------|
| "bad", "terrible", "everywhere", "whole field", "never seen this before", "worst I have seen", "out of control", "lost cause" | high |
| "some", "moderate", "spreading", "getting worse", "more than last week", "quite a bit", "a lot of" | medium |
| "a few", "small patch", "just noticed", "isolated", "one spot", "not