io.github.Cropgraph/cropgraph

Looks up whether two specific crops have a known beneficial or antagonist relationship. Returns the relationship detail (mechanism, description, strength, source) or a `found: false` result when no relationship is in the fixture. Relationships are directed because mechanisms are often asymmetric (corn provides structural support to bean; bean fixes nitrogen for corn: two distinct edges). The tool falls back to the reverse direction transparently, so order of arguments rarely matters. Accepts slugs or common names for both crops.

Validates a multi-year sequence of crops planted in the same bed. `crops[0]` is year 1, `crops[1]` is year 2, and so on. Reports each violation (a crop family replants inside its required year-gap, e.g. tomato in year 1 then pepper in year 2 violates the 3-year nightshade gap) and each warning (a family lands directly after one it should never follow, e.g. cucurbit after malvaceae). Returns `{ sequence: [{slug, family}], issues: [...], ok: boolean }`. Use the `severity` field to triage: `violation` is a hard rule break, `warning` is a soft caution. Accepts slugs or common names. Useful for AI agents validating a 3-5 year garden plan or asking 'what should I plant after my tomatoes?'.

Returns the full record for one beneficial insect, microbe, or friend-not-foe invertebrate from the bundled 200+ entry beneficial insects fixture (Xerces Society, Cornell Cooperative Extension biocontrol fact sheets, UC IPM Natural Enemies Gallery, UF/IFAS Featured Creatures, USDA-ARS sources). The response is a composite intelligence shape with: identification cues, garden role, habitat needs, the plants that attract this beneficial, the crops it protects via prey relationships (aggregated from preyOn into affected crops), and concrete protection tips. Categories covered: `predator`, `parasitoid`, `pollinator`, `decomposer`, `microbial-control`. Use this when the question is 'what is this insect?' and the answer is a beneficial. Use `get_pest_intelligence` when the answer is a pest. Use `get_verdict` to classify first without committing to a tool.

Returns companion (beneficial) and antagonist (harmful) plants for a crop, drawn from the bundled 121-edge companion fixture (USDA Extension / Xerces Society / SARE sources). Each relationship has a categorized mechanism (12 types: `nitrogen_fixing`, `pest_repellent`, `allelopathic`, `disease_vector`, `pollinator_attractor`, `trap_crop`, `shade_provider`, `ground_cover`, `structural_support`, `nutrient_competition`, `space_efficiency`, `flavor_enhancement`), a gardener-facing description, an evidence-strength grade (`strong` = empirical research, `moderate` = widely corroborated traditional, `weak` = folk only), and a citation. Strength grades are honest: most companion-planting lore is `moderate`; only Three Sisters N-cycling, French marigold nematode suppression, allium/Rhizobium inhibition of legumes, nightshade disease sharing, and a handful of pollinator-attractor relationships are `strong`. Accepts slug or common name. No API key required; works offline.

Returns the full crop calendar entry: planting windows, days to harvest, zone range, sowing/transplant guidance, climate modifiers, and citation. Look up by slug, common name, or scientific name. Match is case-insensitive. Returns an error when the calendar has no entry for the query.

Returns the pests and diseases recorded for a crop, drawn from the bundled 506-entry organic-first pest fixture (Cornell, UC IPM, UF/IFAS, Penn State, OSU, WSU, Texas A&M sources). Each entry carries: `pest` (kebab-case slug, separate namespace from crop slugs), `type` (`pest` for insects/mites/mollusks/nematodes/vertebrates, `disease` for fungi/oomycetes/bacteria/viruses/disorders), `severity` (`low` / `moderate` / `high` / `severe`), `symptoms` (diagnostic prose written for a gardener with a hand lens), `organicManagement` (ordered list of OMRI-listed materials, biocontrols, and physical/cultural practices), `prevention` (cultural and pre-planting practices), `regions` (`all` or informal labels like `southern-us`, `pnw`, `arid`), and a citation. Sorted by severity desc, then alphabetically. The fixture is curated, not exhaustive; absence of an entry is not absence of pressure. Pair with `get_companions` to find pest-repellent companion plants for the same crop. Accepts slug or common name. No API key required; works offline.

Returns all crop calendar entries whose zone range includes the supplied USDA zone, optionally filtered by category. Pure metadata, does NOT consider the current date. For 'what to plant now' use `get_planting_plan` instead. Useful for browsing what's possible in a zone, planning beds, or generating seed lists.

Returns the USDA hardiness zone (1a..13b) and typical first/last frost dates for a US location. Provide either lat+lng (resolves to nearest ZIP centroid in the bundled 40,283-ZIP PRISM 2023 dataset) or a 5-digit zip (exact match when present). The zone object includes the 5°F temperature band (min/max winter °F), and frostDates includes lastSpring (MM-DD), firstFall (MM-DD), and seasonDays. Coastal, mountain, and desert microclimates can shift frost dates 2-3 weeks from the table; surface this caveat to gardeners. No API key required; works fully offline.

Returns the full record for one pest or disease across every crop it touches: aggregated severity grades, the union of regions of significance, and per-crop symptoms and organic management. Use this when the question is 'tell me about cabbage worm' (a single pest across crops) rather than 'what hits cabbage' (`get_crop_pests`). Returns an error when the pest slug isn't in the fixture. Use `get_crop_pests` first to discover pest slugs for a given crop. Common slugs include: tomato-hornworm, late-blight, early-blight, cabbage-worm, cabbage-looper, squash-bug, squash-vine-borer, cucumber-beetle-striped, cucumber-beetle-spotted, flea-beetle, japanese-beetle, colorado-potato-beetle, spider-mite, aphid-green-peach, powdery-mildew, downy-mildew, fusarium-wilt, verticillium-wilt, septoria-leaf-spot, bacterial-wilt, mexican-bean-beetle, slug, cutworm, corn-earworm, spotted-wing-drosophila.

Returns the full 'now what?' answer after a pest is identified: severity verdict (`foe` / `nuisance` / `cosmetic`), immediate action steps drawn from the pest's organic management list, seasonal prevention practices, companion plant deterrents and trap crops, the full list of beneficial predators and parasitoids with the 'wait before spraying' guidance, friend-or-foe lookalikes, and rotation advice when applicable. When `plant` is supplied, returns crop-specific symptoms, that crop's companion deterrents, and rotation advice for that crop. Without `plant`, the response uses the first crop entry as the symptom reference and falls back to the derived pest-companion-map for general deterrent suggestions. This is the powering shape for a consumer pest-identification app: one call gives the gardener everything actionable about the identified pest in context.

Returns a list of crops to plant in the supplied date window, drawn from the bundled 1000-crop calendar (USDA Cooperative Extension publications). Provide a USDA zone string ('5b', '8b') OR a coordinate pair / zip; coordinates resolve to a zone via the same lookup as `get_hardiness_zone`. Each suggestion has: action (start_indoors / direct_sow / transplant / plant_now), windowStart..windowEnd (ISO dates anchored to the zone's typical frost dates), daysToHarvest range, and expectedHarvestEarliest. If expectedHarvestEarliest lands past the typical first fall frost the crop is unlikely to finish; surface that to the user. Climate-aware: pass `climate_type` to apply per-climate window shifts and notes. When you supply lat/lng or zip without `climate_type`, the tool auto-detects the climate from coordinates. The response echoes `climateType`. For a strict view pass padDays:0 (default). For 'almost in window' pass padDays:7 or 14. No API key required; works offline.

Returns the botanical rotation family and rotation rules for a crop, drawn from the bundled 12-family partition of all 1000 calendar crops (USDA Cooperative Extension, SARE, Rodale sources). Each crop is in exactly one family (nightshades, brassicas, cucurbits, alliums, legumes, umbellifers, grasses, amaranthaceae, composites, mints, malvaceae, or miscellaneous). Per family: `rotationYears` (recommended minimum years between successive plantings of the family in the same bed), `followWith` (families that work well after this one), `neverFollow` (families to avoid following), and `reason` (the dominant pathogens or pests behind the rule). Returns `partners.follow` (crops in recommended follow-with families) and `partners.avoid` (crops in never-follow families). The miscellaneous bucket covers perennial fruit, nuts, asparagus, rhubarb, mushrooms, aquatic crops, and ornamental flowers; their rotation needs are crop-specific. Accepts slug or common name. No API key required; works offline.

Returns the time-sequenced succession chain for a crop, drawn from the bundled 33-chain fixture (Johnny's Selected Seeds, Cornell Extension, UC ANR, SARE, Eliot Coleman's New Organic Grower). Each chain has an ordered list of phases. Each phase carries: `crop` (calendar slug), `sowMethod` (`direct_sow` / `transplant` / `start_indoors`), `intervalWeeks` (null means a single sowing, otherwise a recurring cadence), `startRelativeToFrost` and `endRelativeToFrost` (days from last spring frost; negative = before LSF, positive = after), optional per-climate `climateNotes`, and gardener-facing `notes`. Categories: `continuous-harvest` (lettuce, spinach, arugula cycles), `root-succession` (radish, carrot, beet, turnip cadences), `legume-succession` (bean / pea relays), `brassica-succession` (broccoli, cabbage spring + fall), `cucurbit-relay` (replacement plantings against vine borer / mildew), `herb-succession` (basil, cilantro, dill cadences), `flower-succession` (zinnia, cosmos, sunflower for continuous cut flowers), `cover-crop-relay` (winter cover → cash crop → fall cover chains). Lookup is by chain slug (e.g. `lettuce-succession`), primary crop slug (e.g. `lettuce-leaf`), or any crop slug that appears as a phase. Pair this tool with `get_succession_plan` to resolve the phases to concrete ISO dates for a zone.

Resolves a succession chain into concrete ISO dates for a location. Provide a USDA zone string ('5b', '8b') OR a coordinate pair / zip; coordinates resolve to a zone via the same lookup as `get_hardiness_zone`. Each returned phase carries `windowStart` and `windowEnd` (ISO dates), and `sowingDates` (the dated sowing events within the window when the chain specifies an `intervalWeeks` cadence). Climate-aware: pass `climate_type` to apply per-climate notes. When you supply lat/lng or zip without `climate_type`, the tool auto-detects climate from coordinates. The response echoes `climateType` and includes the resolved `zone` and `frostDates`. Use `year` to anchor the plan to a specific calendar year (defaults to the current UTC year). No API key required; works offline.

Returns the friend-or-foe verdict for any insect, microbe, or invertebrate slug by checking the beneficial-insects database first, then the pest-disease database. Useful as a routing call before deciding whether to call `get_beneficial_insect` or `get_pest_intelligence`. Return values: `friend` (entry exists in beneficial-insects), `foe` (entry exists in pest-disease with severity high or severe), `nuisance` (pest-disease severity moderate), `cosmetic` (pest-disease severity low), `neutral` (slug not recognized in either fixture).

Returns the full beneficial insects catalog or a category-filtered subset. Categories: `predator` (60+ entries: ladybugs, lacewings, ground beetles, mantises, assassin bugs, predatory mites, soldier bugs, spiders, hover fly larvae), `parasitoid` (40+ entries: braconid wasps including Cotesia hornworm specialist, Trichogramma egg parasitoids, Encarsia and Eretmocerus whitefly parasitoids, tachinid flies, ichneumon wasps), `pollinator` (50+ entries: honey bees, bumble bees including federally listed Bombus affinis, mason bees, leafcutter bees, sweat bees, mining bees, carpenter bees, squash bees, butterflies, sphinx moths), `decomposer` (30 entries: earthworms, dung beetles, pill bugs, millipedes, springtails, black soldier fly larva, soil mites), `microbial-control` (20+ entries: entomopathogenic nematodes, Bt strains, Beauveria bassiana, Trichoderma, mycorrhizal fungi, milky spore). Each entry has slug, commonName, scientificName, category, preyOn, attractedBy, habitatNeeds, gardenRole, identificationTips, seasonalPresence, regions, and citation. Sorted alphabetically by common name.

Evaluates a group of 2-20 crops planted in the same bed. Discovers all pairwise relationships (beneficial and antagonist) among the crops in the input, deduplicates by canonical pair order, and surfaces warnings when one crop antagonizes 2+ others (the hub-antagonist pattern; fennel-herb is the canonical example). Returns `{ crops, beneficial[], antagonist[], warnings[] }`. Each pair is reported once; if both storage directions exist, the strongest edge is chosen. Accepts slugs or common names. Crops with no known relationship to any other crop in the bed are silently absent from the relationship lists.

Searches the bundled 1000-crop calendar by common name, scientific name, or substring. For a focused 'find me the canonical entry for X' use `get_crop_details` instead. Filter by zone or category to narrow matches.