paleoscope.aguvener.workers.dev

{
  "name": "read_state",
  "kind": "answer",
  "impl": "imperative",
  "description": "Report everything about the workspace in one call: the dataset, the active PCA basis, every filter in force, how many individuals are visible, what the user has selected, the live set handles, saved findings, the recent history of what both of you did, and which tools are dormant and why.\nReturns: dataset, view, sets, notes, history, tools.\nUse when: starting cold, or after losing track of what changed.\nChanges: nothing.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  }
}

{
  "name": "read_plot",
  "kind": "answer",
  "impl": "imperative",
  "description": "Render a panel as an ASCII density grid so you can see the shape the user is looking at: where the mass sits, where the empty corridors are, and where a set sits relative to both. Roughly 250 tokens.\nReturns: a character grid, the density key, the frame, and lettered landmark populations.\nUse when: you need the structure of the scatter rather than statistics about it — especially before explaining why a selection looks unusual.\nChanges: nothing.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "panel": {
        "type": "string",
        "description": "Which panel to render. \"pca\" for ancestry structure, \"map\" for geography.",
        "enum": [
          "pca",
          "map"
        ],
        "default": "pca"
      },
      "mark": {
        "type": "string",
        "description": "A set handle to stamp onto the grid with \"O\", e.g. \"selection\" or \"s3\".",
        "default": "selection"
      },
      "width": {
        "type": "integer",
        "description": "Grid width in characters. 24-96, default 56.",
        "minimum": 24,
        "maximum": 96,
        "default": 56
      },
      "height": {
        "type": "integer",
        "description": "Grid height in characters. 8-32, default 20.",
        "minimum": 8,
        "maximum": 32,
        "default": 20
      },
      "frame": {
        "type": "string",
        "description": "\"auto\" (default) zooms in once the visible set has collapsed into a corner; \"basis\" keeps the fixed frame so coordinates are comparable across calls; \"fit\" always zooms to what is visible.",
        "enum": [
          "auto",
          "basis",
          "fit"
        ],
        "default": "auto"
      }
    }
  }
}

{
  "name": "read_timeline",
  "kind": "answer",
  "impl": "imperative",
  "description": "Summarize a cohort as evenly spaced time bins, including its date uncertainty and age summary. Use this when the shape or gaps in a temporal distribution matter. Changes nothing.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "set": {
        "type": "string",
        "description": "Cohort handle. Defaults to visible."
      },
      "bins": {
        "type": "integer",
        "description": "Number of bins, 4-60. Default 16.",
        "minimum": 4,
        "maximum": 60,
        "default": 16
      },
      "fromBP": {
        "type": "integer",
        "description": "Optional youngest bound in BP.",
        "minimum": 0,
        "maximum": 100000
      },
      "toBP": {
        "type": "integer",
        "description": "Optional oldest bound in BP.",
        "minimum": 0,
        "maximum": 100000
      }
    }
  }
}

{
  "name": "read_population_profile",
  "kind": "answer",
  "impl": "imperative",
  "description": "Return the dates, localities, publications, haplogroups, quality assessments and PCA summary for one exact population label in a cohort. Use after find_populations resolves the label. Changes nothing.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "population": {
        "type": "string",
        "description": "Exact population label, such as Turkey_N."
      },
      "set": {
        "type": "string",
        "description": "Cohort to search. Defaults to visible."
      }
    },
    "required": [
      "population"
    ]
  }
}

{
  "name": "read_sample",
  "kind": "answer",
  "impl": "imperative",
  "description": "Return the full record for one individual by AADR genetic ID: population, locality, radiocarbon or contextual date, coordinates, PCA position, SNP coverage, uniparental haplogroups, quality assessment and the publication that reported it.\nReturns: one individual record.\nUse when: you have an exact ID and need its details.\nChanges: nothing.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "geneticId": {
        "type": "string",
        "description": "AADR genetic ID, e.g. \"Loschbour.AG\" or \"Tep006.WGC.SG\"."
      }
    },
    "required": [
      "geneticId"
    ]
  }
}

{
  "name": "find_populations",
  "kind": "answer",
  "impl": "imperative",
  "description": "Search population labels by substring, returning matches with sample counts, date ranges and PCA centroids, plus a set handle covering all of them.\nReturns: matching populations and a set handle.\nUse when: turning a vague name (\"Anatolian Neolithic\") into the exact labels the data uses (\"Turkey_N\"). Do this before filtering by population.\nChanges: nothing.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Case-insensitive substring of the label, e.g. \"Yamnaya\" or \"Natufian\"."
      },
      "limit": {
        "type": "integer",
        "description": "Maximum matches to return. 1-40, default 15.",
        "minimum": 1,
        "maximum": 40,
        "default": 15
      }
    },
    "required": [
      "query"
    ]
  }
}

{
  "name": "find_publications",
  "kind": "answer",
  "impl": "imperative",
  "description": "Search publication titles and DOI values, returning source counts and a reusable cohort of their samples. Use when tracing evidence or building a publication-specific cohort. Changes nothing.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "At least two characters from a title or DOI."
      },
      "limit": {
        "type": "integer",
        "description": "Maximum sources, 1-30. Default 12.",
        "minimum": 1,
        "maximum": 30,
        "default": 12
      }
    },
    "required": [
      "query"
    ]
  }
}

{
  "name": "build_cohort",
  "kind": "act",
  "impl": "imperative",
  "description": "Create a cohort from explicit metadata criteria without changing the visible filters. Use when an analysis needs a reusable group while preserving the user's current view. Changes only the visible cohort list.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "within": {
        "type": "string",
        "description": "Optional set to restrict. Defaults to all."
      },
      "region": {
        "type": "string",
        "description": "Named region, as in set_filter.",
        "enum": [
          "west-eurasia",
          "anatolia",
          "the-levant",
          "europe",
          "south-east-europe",
          "the-caucasus",
          "the-pontic-caspian-steppe",
          "central-asia",
          "the-iranian-plateau",
          "north-africa",
          "the-british-isles",
          "the-iberian-peninsula",
          "world"
        ]
      },
      "bbox": {
        "type": "object",
        "description": "Explicit bounding box, as an alternative to region.",
        "properties": {
          "west": {
            "type": "number",
            "description": "Western longitude.",
            "minimum": -180,
            "maximum": 180
          },
          "east": {
            "type": "number",
            "description": "Eastern longitude.",
            "minimum": -180,
            "maximum": 180
          },
          "south": {
            "type": "number",
            "description": "Southern latitude.",
            "minimum": -90,
            "maximum": 90
          },
          "north": {
            "type": "number",
            "description": "Northern latitude.",
            "minimum": -90,
            "maximum": 90
          }
        }
      },
      "population": {
        "type": "string",
        "description": "Population label substring."
      },
      "locality": {
        "type": "string",
        "description": "Locality substring."
      },
      "publication": {
        "type": "string",
        "description": "Publication substring."
      },
      "dateMethod": {
        "type": "string",
        "description": "Dating method substring."
      },
      "mtHaplogroup": {
        "type": "string",
        "description": "mtDNA haplogroup prefix or substring."
      },
      "yHaplogroup": {
        "type": "string",
        "description": "Y haplogroup prefix or substring."
      },
      "molecularSex": {
        "type": "string",
        "description": "Recorded molecular sex substring."
      },
      "fromBP": {
        "type": "integer",
        "description": "Youngest age in BP.",
        "minimum": 0,
        "maximum": 100000
      },
      "toBP": {
        "type": "integer",
        "description": "Oldest age in BP.",
        "minimum": 0,
        "maximum": 100000
      },
      "dateMode": {
        "type": "string",
        "description": "How date uncertainty matches.",
        "enum": [
          "point",
          "overlap",
          "contained"
        ],
        "default": "point"
      },
      "minSnps": {
        "type": "integer",
        "description": "Minimum SNPs hit.",
        "minimum": 0
      },
      "passOnly": {
        "type": "boolean",
        "description": "Keep only quality-passing samples."
      },
      "era": {
        "type": "string",
        "description": "Ancient, present, or both.",
        "enum": [
          "ancient",
          "present",
          "both"
        ],
        "default": "both"
      },
      "name": {
        "type": "string",
        "description": "Short label for the resulting cohort."
      }
    },
    "required": [
      "name"
    ]
  }
}

{
  "name": "find_outliers",
  "kind": "answer",
  "impl": "imperative",
  "description": "Rank individuals by how far each sits from the centre of its OWN population cluster, in units of that population's own spread. This is the standard first pass for spotting contamination, mislabelled samples, relatives or genuine migrants.\nReturns: a ranked list and a set handle for the hits.\nUse when: asked what is unusual, or before concluding that a group is homogeneous.\nChanges: nothing, unless \"select\" is true, which highlights the hits for the user.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "set": {
        "type": "string",
        "description": "Set handle to search within. Default \"visible\".",
        "default": "visible"
      },
      "limit": {
        "type": "integer",
        "description": "How many to return. 1-25, default 10.",
        "minimum": 1,
        "maximum": 25,
        "default": 10
      },
      "minPopulationSize": {
        "type": "integer",
        "description": "Ignore populations with fewer members than this, since spread is meaningless in tiny groups. 3-50, default 6.",
        "minimum": 3,
        "maximum": 50,
        "default": 6
      },
      "select": {
        "type": "boolean",
        "description": "Also highlight the hits in every panel so the user can look at them.",
        "default": false
      }
    }
  }
}

{
  "name": "find_neighbours",
  "kind": "answer",
  "impl": "imperative",
  "description": "Find the individuals sitting closest to one individual in the current PCA basis, searching within a set.\nReturns: ranked neighbours and a set handle.\nUse when: answering \"who does this sample cluster with\", which is usually the real question behind \"what is this\".\nChanges: nothing.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "geneticId": {
        "type": "string",
        "description": "The individual to search around."
      },
      "set": {
        "type": "string",
        "description": "Set handle to search within. Default \"visible\".",
        "default": "visible"
      },
      "limit": {
        "type": "integer",
        "description": "How many neighbours. 1-25, default 10.",
        "minimum": 1,
        "maximum": 25,
        "default": 10
      }
    },
    "required": [
      "geneticId"
    ]
  }
}

{
  "name": "set_filter",
  "kind": "act",
  "impl": "imperative",
  "description": "Apply filters. Every argument is optional and merges into the filters already in force, so this can be called repeatedly to narrow down. The user can undo it.\nReturns: the resulting count and a summary of what is left.\nUse when: narrowing to a time, place, population or quality band. Pass dryRun to see what a filter would yield without changing the screen — prefer that while you are still deciding.\nChanges: the visible set in all three panels, unless dryRun.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "dryRun": {
        "type": "boolean",
        "description": "Compute the result without touching the user's view.",
        "default": false
      },
      "fromBP": {
        "type": "integer",
        "description": "Youngest age to include, years before present. e.g. 6000.",
        "minimum": 0,
        "maximum": 50000
      },
      "toBP": {
        "type": "integer",
        "description": "Oldest age to include, years before present. e.g. 9000.",
        "minimum": 0,
        "maximum": 50000
      },
      "region": {
        "type": "string",
        "description": "A named region: west-eurasia, anatolia, the-levant, europe, south-east-europe, the-caucasus, the-pontic-caspian-steppe, central-asia, the-iranian-plateau, north-africa, the-british-isles, the-iberian-peninsula, world.",
        "enum": [
          "west-eurasia",
          "anatolia",
          "the-levant",
          "europe",
          "south-east-europe",
          "the-caucasus",
          "the-pontic-caspian-steppe",
          "central-asia",
          "the-iranian-plateau",
          "north-africa",
          "the-british-isles",
          "the-iberian-peninsula",
          "world"
        ]
      },
      "bbox": {
        "type": "object",
        "description": "An explicit geographic box in degrees. Use \"region\" if one fits.",
        "properties": {
          "west": {
            "type": "number",
            "description": "e.g. 25.5",
            "minimum": -180,
            "maximum": 180
          },
          "east": {
            "type": "number",
            "description": "e.g. 45",
            "minimum": -180,
            "maximum": 180
          },
          "south": {
            "type": "number",
            "description": "e.g. 35.5",
            "minimum": -90,
            "maximum": 90
          },
          "north": {
            "type": "number",
            "description": "e.g. 42.5",
            "minimum": -90,
            "maximum": 90
          }
        }
      },
      "population": {
        "type": "string",
        "description": "Substring of the population label, e.g. \"Yamnaya\". Case-insensitive."
      },
      "locality": {
        "type": "string",
        "description": "Substring of the archaeological locality."
      },
      "publication": {
        "type": "string",
        "description": "Substring of a publication title."
      },
      "dateMethod": {
        "type": "string",
        "description": "Substring of the recorded dating method."
      },
      "mtHaplogroup": {
        "type": "string",
        "description": "mtDNA haplogroup prefix or substring."
      },
      "yHaplogroup": {
        "type": "string",
        "description": "Y haplogroup prefix or substring."
      },
      "molecularSex": {
        "type": "string",
        "description": "Recorded molecular sex substring."
      },
      "dateMode": {
        "type": "string",
        "description": "Match the central date, any uncertainty overlap, or a contained interval.",
        "enum": [
          "point",
          "overlap",
          "contained"
        ]
      },
      "minSnps": {
        "type": "integer",
        "description": "Minimum SNPs hit on the compatibility_HO panel, e.g. 20000.",
        "minimum": 0,
        "maximum": 276725
      },
      "passOnly": {
        "type": "boolean",
        "description": "Keep only individuals whose AADR assessment begins \"Pass\"."
      },
      "era": {
        "type": "string",
        "description": "Restrict to ancient, present-day, or both.",
        "enum": [
          "ancient",
          "present",
          "both"
        ]
      }
    }
  }
}

{
  "name": "set_basis",
  "kind": "act",
  "impl": "imperative",
  "description": "Switch which principal-component basis the scatter shows. \"we\" is computed on present-day West Eurasian individuals and is the conventional frame for reading European and Near Eastern ancestry. \"global\" is computed on a worldwide panel and separates continental ancestries.\nReturns: the new basis.\nUse when: individuals are not projected onto the current basis, or the question is continental rather than regional.\nChanges: the scatter plot redraws; axis extents are fixed per basis.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "basis": {
        "type": "string",
        "description": "Which basis to show.",
        "enum": [
          "we",
          "global"
        ]
      }
    },
    "required": [
      "basis"
    ]
  }
}

{
  "name": "clear_filters",
  "kind": "act",
  "impl": "imperative",
  "description": "Remove every filter and show the whole dataset again. Does not touch the selection.\nReturns: the resulting count.\nUse when: a filter combination has emptied the view, or you are starting a new line of enquiry.\nChanges: all three panels.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  }
}

{
  "name": "focus_sample",
  "kind": "act",
  "impl": "imperative",
  "description": "Ring one individual in all three panels, centre the map on its site and scroll the detail list to it.\nReturns: the focused individual.\nUse when: you want the human to look at something specific. This is how you point.\nChanges: a highlight ring and the map centre. Filters and selection are untouched.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "geneticId": {
        "type": "string",
        "description": "AADR genetic ID to ring."
      }
    },
    "required": [
      "geneticId"
    ]
  }
}

{
  "name": "select",
  "kind": "act",
  "impl": "imperative",
  "description": "Replace the user's selection, highlighting those individuals in orange across the map, the scatter and the detail list. The human sees exactly what was selected and can undo it or redraw it by hand.\nReturns: the new selection size and summary.\nUse when: you have found something and want it on screen rather than in prose.\nChanges: the selection in all three panels.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "set": {
        "type": "string",
        "description": "Set handle to select, e.g. \"s3\"."
      },
      "geneticIds": {
        "type": "array",
        "description": "Explicit AADR genetic IDs, as an alternative to a set handle.",
        "items": {
          "type": "string"
        }
      },
      "population": {
        "type": "string",
        "description": "Select every visible individual whose population contains this substring."
      }
    }
  }
}

{
  "name": "save_set",
  "kind": "act",
  "impl": "imperative",
  "description": "Name a set so it survives and can be compared later. Named sets appear in the sidebar, persist across reloads, and unlock compare_sets once two exist.\nReturns: the saved set.\nUse when: a group is worth returning to — before moving on to a different one.\nChanges: the saved-sets list in the sidebar.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "set": {
        "type": "string",
        "description": "Handle to save. Default \"selection\".",
        "default": "selection"
      },
      "name": {
        "type": "string",
        "description": "Short name, e.g. \"Anatolian outliers\"."
      }
    },
    "required": [
      "name"
    ]
  }
}

{
  "name": "combine_sets",
  "kind": "act",
  "impl": "imperative",
  "description": "Build a new set from two existing ones.\nReturns: a new set handle and its size.\nUse when: you need \"the outliers that are also Neolithic\", or \"everything visible except what I already saved\". Cheaper and more exact than re-filtering.\nChanges: nothing on screen; the new set appears in the sidebar list.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "op": {
        "type": "string",
        "description": "union = in either; intersect = in both; minus = in a but not b.",
        "enum": [
          "union",
          "intersect",
          "minus"
        ]
      },
      "a": {
        "type": "string",
        "description": "First set handle, e.g. \"visible\"."
      },
      "b": {
        "type": "string",
        "description": "Second set handle, e.g. \"selection\"."
      }
    },
    "required": [
      "op",
      "a",
      "b"
    ]
  }
}

{
  "name": "explain_set",
  "kind": "act",
  "impl": "imperative",
  "description": "Work out what a set of individuals is: which populations they belong to, when and where they come from, which reference populations they sit nearest in the current PCA basis, and whether any is an outlier within its own population.\nReturns: composition, date and geography summary, nearest populations, outlier status, and optionally the individual records.\nUse when: the user selects points by eye and asks \"what are these?\". This is the main analytical tool.\nChanges: nothing.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "set": {
        "type": "string",
        "description": "Set handle to explain. Default \"selection\".",
        "default": "selection"
      },
      "nearest": {
        "type": "integer",
        "description": "How many nearby reference populations to name. 1-15, default 6.",
        "minimum": 1,
        "maximum": 15,
        "default": 6
      },
      "era": {
        "type": "string",
        "description": "Compare against present-day populations for a familiar frame, ancient ones for an archaeological one.",
        "enum": [
          "ancient",
          "present",
          "both"
        ],
        "default": "both"
      },
      "rows": {
        "type": "integer",
        "description": "Include this many individual records. 0-40, default 0.",
        "minimum": 0,
        "maximum": 40,
        "default": 0
      }
    }
  }
}

{
  "name": "note",
  "kind": "act",
  "impl": "imperative",
  "description": "Write a finding into the shared journal, optionally attached to a set. It appears in the sidebar, survives reload, is returned by read_state, and goes into the CSV export.\nReturns: the stored note.\nUse when: you and the user have worked something out. A session that leaves no record was half wasted — write the conclusion down before moving on.\nChanges: the notes list in the sidebar.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "text": {
        "type": "string",
        "description": "The finding, in one or two sentences, e.g. \"Tep006 sits 4.3 spreads from the Turkey_N centroid, toward the Iranian cline.\""
      },
      "about": {
        "type": "string",
        "description": "A set handle the finding is about, e.g. \"selection\" or \"s3\"."
      },
      "kind": {
        "type": "string",
        "description": "Classify the finding.",
        "enum": [
          "observation",
          "hypothesis",
          "caveat"
        ],
        "default": "observation"
      },
      "status": {
        "type": "string",
        "description": "Research status for the finding.",
        "enum": [
          "open",
          "supported",
          "rejected"
        ],
        "default": "open"
      },
      "tags": {
        "type": "array",
        "description": "Up to eight short search tags.",
        "items": {
          "type": "string"
        },
        "maxItems": 8
      }
    },
    "required": [
      "text"
    ]
  }
}

{
  "name": "undo",
  "kind": "act",
  "impl": "imperative",
  "description": "Reverse the last change to the view or selection, whoever made it.\nReturns: the restored state.\nUse when: a filter you applied was wrong. Prefer set_filter with dryRun so you do not need this.\nChanges: restores the previous filters, basis and selection.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  }
}

{
  "name": "read_selection",
  "kind": "answer",
  "impl": "imperative",
  "description": "Return the individuals the user has selected by lasso, click or map box. This selection exists only in the browser — it is a gesture, not a query any server could answer — which is why it has to be handed over as a tool.\nReturns: the individual records plus a summary.\nUse when: the user says \"these\", \"those\" or \"this one\". Prefer explain_set for the analysis; use this when you need the raw records.\nChanges: nothing.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "limit": {
        "type": "integer",
        "description": "How many records to include. 1-40, default 20.",
        "minimum": 1,
        "maximum": 40,
        "default": 20
      }
    }
  }
}

{
  "name": "export_workspace",
  "kind": "act",
  "impl": "declarative",
  "description": "Download the complete local PaleoScope workspace, including cohorts, findings, filters, history, layout and panel viewports, as JSON.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  }
}

{
  "name": "export_research_report",
  "kind": "act",
  "impl": "declarative",
  "description": "Export the visible PaleoScope research state, saved cohorts, comparison and findings as a local Markdown report.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string"
      }
    }
  }
}

{
  "name": "export_data",
  "kind": "act",
  "impl": "declarative",
  "description": "Export the current selection, visible samples, or a saved cohort as a local CSV or JSON file through the visible export form.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "filename": {
        "type": "string"
      },
      "scope": {
        "type": "string",
        "enum": [
          "selection",
          "visible"
        ]
      },
      "format": {
        "type": "string",
        "enum": [
          "csv",
          "json"
        ]
      }
    }
  }
}