mirror of
https://github.com/hanzoai/insights.git
synced 2026-11-03 00:52:32 +00:00
zeekay
1b367e2b62
The tree was a debranded snapshot of upstream taken around 2026-02-20, and upstream has moved about five months since. This replaces it with upstream master, mechanically re-derived: bin/debrand does the rename, and the pipeline and squashed migrations are restored from the shipped tree. Not a merge. The previous import replaced the tree wholesale in a single commit, so there is no shared content history to merge against. Reproducing the rename on the new tree is what actually converges. What survives: .hanzo/workflows, the Dockerfiles and bin/docker* entrypoints, compose files, LLM.md, and insights/migrations. The squashed initial migration is load-bearing — the live database records it by name, so upstream's ~918 individual migrations cannot come back. Nine products are dropped as unreferenced. Twenty-one more that we do not run are kept anyway because the core app still imports them; unpicking those is a refactor and does not belong in a rebase. This base does not build yet, and the reasons are not in the rename: upstream now wants Python 3.13.13 against our 3.12.12 and Django 5.2 against our 4.2, and the dependency manifests still name upstream packages that we republish under our own names. Those are decisions, not renames.
249 lines
10 KiB
YAML
249 lines
10 KiB
YAML
# MCP tool definition — tool entries are scaffolded from the OpenAPI schema.
|
|
# The tool list and operation IDs are kept in sync automatically:
|
|
# pnpm --filter=@hanzo/mcp run scaffold-yaml -- --sync-all
|
|
#
|
|
# To enable a tool, set enabled: true and add required scopes + annotations.
|
|
# All other fields (title, description, enrich_url, etc.) are yours to configure.
|
|
category: Cohorts
|
|
feature: cohorts
|
|
url_prefix: /cohorts
|
|
ui_apps:
|
|
cohort:
|
|
type: detail
|
|
view_prop: cohort
|
|
cohort-list:
|
|
type: list
|
|
detail_tool: cohorts-retrieve
|
|
tools:
|
|
cohorts-activity-retrieve:
|
|
operation: cohorts_activity_retrieve
|
|
enabled: false
|
|
cohorts-add-persons-to-static-cohort-partial-update:
|
|
operation: cohorts_add_persons_to_static_cohort_partial_update
|
|
enabled: true
|
|
scopes:
|
|
- cohort:write
|
|
annotations:
|
|
readOnly: false
|
|
destructive: false
|
|
idempotent: false
|
|
title: Add persons to static cohort
|
|
description: >-
|
|
Add persons to a static cohort by their UUIDs. Only works for static cohorts (is_static: true).
|
|
|
|
|
|
Intended for small, ad-hoc additions — pass at most ~20 person UUIDs per call. To build or grow a static
|
|
cohort from a larger set, do NOT loop this tool over many UUIDs; instead create the cohort from a query
|
|
('cohorts-create' with 'is_static: true' and a 'query'), or add to an existing static cohort by setting a
|
|
'query' on it via 'cohorts-partial-update'. The server then runs the query and inserts every matching person
|
|
in a single call, with no row limit.
|
|
cohorts-all-activity-retrieve:
|
|
operation: cohorts_all_activity_retrieve
|
|
enabled: false
|
|
cohorts-calculation-history-retrieve:
|
|
operation: cohorts_calculation_history_retrieve
|
|
enabled: false
|
|
cohorts-create:
|
|
operation: cohorts_create
|
|
enabled: true
|
|
scopes:
|
|
- cohort:write
|
|
annotations:
|
|
readOnly: false
|
|
destructive: false
|
|
idempotent: false
|
|
enrich_url: '{id}'
|
|
title: Create cohort
|
|
description: >-
|
|
Create a cohort (a saved group of persons). Two kinds:
|
|
|
|
|
|
- Dynamic cohort (default): provide 'filters' with AND/OR groups of property conditions (person properties,
|
|
behavioral filters, or cohort references). Membership is recalculated automatically.
|
|
|
|
- Static cohort ('is_static: true'): a fixed snapshot of persons. PREFER populating it from a 'query' (see
|
|
below) — the server runs the query and inserts every matching person in a single call, with no row limit.
|
|
Only use 'cohorts-add-persons-to-static-cohort-partial-update' for tiny, ad-hoc additions (up to ~20
|
|
people).
|
|
|
|
|
|
Populate a static cohort from a query by setting BOTH 'is_static: true' and 'query'. 'query' accepts a
|
|
InsightsQLQuery (raw SQL) or an ActorsQuery (the actors behind a product-analytics insight such as trends or
|
|
funnels). The query MUST expose the person identifier under one of these column names, checked in this
|
|
order: 'person_id', 'actor_id', 'id', or 'distinct_id'. Selecting from the 'events' or 'persons' tables
|
|
resolves the actor automatically. If none of those columns is present the call fails with "Could not find a
|
|
person_id, actor_id, id, or distinct_id column in the query".
|
|
|
|
|
|
ALWAYS validate the query before saving it: run a InsightsQLQuery through the 'execute-sql' tool, and an
|
|
ActorsQuery through its matching 'query-*-actors' tool (e.g. 'query-trends-actors',
|
|
'query-lifecycle-actors'). Only pass a 'query' that returned successfully — this catches column-name and
|
|
syntax errors before they fail cohort population.
|
|
|
|
|
|
Example — from SQL (InsightsQLQuery), alias the id column as person_id:
|
|
|
|
{"name": "Power users", "is_static": true, "query": {"kind": "InsightsQLQuery", "query": "SELECT person_id FROM
|
|
events WHERE event = '$pageview' GROUP BY person_id HAVING count() > 100"}}
|
|
|
|
|
|
Example — from a product-analytics trends insight (ActorsQuery):
|
|
|
|
{"name": "Viewed pricing last 7d", "is_static": true, "query": {"kind": "ActorsQuery", "source": {"kind":
|
|
"InsightActorsQuery", "source": {"kind": "TrendsQuery", "series": [{"kind": "EventsNode", "event":
|
|
"$pageview"}], "dateRange": {"date_from": "-7d"}}}}}
|
|
exclude_params:
|
|
- groups
|
|
- deleted
|
|
- version
|
|
- pending_version
|
|
- is_calculating
|
|
- created_by
|
|
- created_at
|
|
- last_calculation
|
|
- errors_calculating
|
|
- last_error_message
|
|
- count
|
|
- experiment_set
|
|
ui_app: cohort
|
|
cohorts-destroy:
|
|
operation: cohorts_destroy
|
|
enabled: false
|
|
cohorts-list:
|
|
operation: cohorts_list
|
|
enabled: true
|
|
scopes:
|
|
- cohort:read
|
|
annotations:
|
|
readOnly: true
|
|
destructive: false
|
|
idempotent: true
|
|
enrich_url: '{id}'
|
|
list: true
|
|
title: List all cohorts
|
|
description: >
|
|
|
|
List all cohorts in the project. Returns a summary of each cohort including id, name, description, count
|
|
(person count), is_static (cohort type), and created_at timestamp. To find a cohort by name, pass 'search'
|
|
rather than listing everything and filtering client-side — it matches the cohort name with fuzzy trigram
|
|
search (tolerates typos and partial words) and orders exact matches first. Use 'cohorts-retrieve' with the
|
|
cohort ID to get full details including filters, calculation status,
|
|
|
|
and query definition.
|
|
param_overrides:
|
|
limit:
|
|
cast: string-int
|
|
offset:
|
|
cast: string-int
|
|
search:
|
|
description: Find cohorts by name. Fuzzy trigram match (tolerates typos and partial words), exact matches ordered first.
|
|
hide_behavioral_cohorts:
|
|
description: Set true to exclude behavioral (event-based) cohorts — not usable in batch workflow audiences.
|
|
ui_app: cohort-list
|
|
response:
|
|
include:
|
|
- id
|
|
- name
|
|
- description
|
|
- count
|
|
- is_static
|
|
- created_at
|
|
cohorts-partial-update:
|
|
operation: cohorts_partial_update
|
|
enabled: true
|
|
scopes:
|
|
- cohort:write
|
|
annotations:
|
|
readOnly: false
|
|
destructive: false
|
|
idempotent: true
|
|
enrich_url: '{id}'
|
|
title: Update cohort
|
|
description: >-
|
|
Update an existing cohort's name, description, or filters. Changing filters on a dynamic cohort triggers
|
|
recalculation. To soft-delete a cohort, set 'deleted: true'.
|
|
|
|
|
|
To add more people to an existing STATIC cohort in bulk, set a 'query' (InsightsQLQuery or ActorsQuery) on it —
|
|
the server runs the query and inserts every newly matched person (existing members are skipped), with no row
|
|
limit. The query must expose the person id under one of these column names, checked in order: 'person_id',
|
|
'actor_id', 'id', or 'distinct_id' (selecting from the 'events' or 'persons' tables resolves the actor
|
|
automatically). Validate the query before saving it — run a InsightsQLQuery through 'execute-sql' and an
|
|
ActorsQuery through its matching 'query-*-actors' tool (e.g. 'query-trends-actors') — and only save one that
|
|
returned successfully. Prefer this over 'cohorts-add-persons-to-static-cohort-partial-update' for anything
|
|
beyond a handful (~20) of people.
|
|
exclude_params:
|
|
- groups
|
|
- version
|
|
- pending_version
|
|
- is_calculating
|
|
- created_by
|
|
- created_at
|
|
- last_calculation
|
|
- errors_calculating
|
|
- last_error_message
|
|
- count
|
|
- experiment_set
|
|
param_overrides:
|
|
id:
|
|
cast: string-int
|
|
ui_app: cohort
|
|
cohorts-persons-retrieve:
|
|
operation: cohorts_persons_retrieve
|
|
enabled: false
|
|
cohorts-retrieve:
|
|
operation: cohorts_retrieve
|
|
enabled: true
|
|
scopes:
|
|
- cohort:read
|
|
annotations:
|
|
readOnly: true
|
|
destructive: false
|
|
idempotent: true
|
|
enrich_url: '{id}'
|
|
title: Get cohort
|
|
description: >
|
|
Get a specific cohort by ID. Returns the cohort name, description, filters (for dynamic cohorts), count of
|
|
matching users, and calculation status.
|
|
param_overrides:
|
|
id:
|
|
cast: string-int
|
|
ui_app: cohort
|
|
response:
|
|
exclude:
|
|
- filters.properties.values.*.values.*.bytecode
|
|
- filters.properties.values.*.values.*.bytecode_error
|
|
- filters.properties.values.*.values.*.conditionHash
|
|
- filters.properties.values.*.bytecode
|
|
- filters.properties.values.*.bytecode_error
|
|
- filters.properties.values.*.conditionHash
|
|
cohorts-rm-person-from-static-cohort-partial-update:
|
|
operation: cohorts_remove_person_from_static_cohort_partial_update
|
|
enabled: true
|
|
scopes:
|
|
- cohort:write
|
|
annotations:
|
|
readOnly: false
|
|
destructive: false
|
|
idempotent: true
|
|
title: Remove person from static cohort
|
|
description: >
|
|
Remove a person from a static cohort by their UUID. Only works for static cohorts (is_static: true). The
|
|
person must exist in the project. Idempotent: removing a person who exists but is not a member of the cohort
|
|
succeeds silently.
|
|
cohorts-staff-list:
|
|
operation: cohorts_staff_list
|
|
enabled: false
|
|
cohorts-staff-recalculate-create:
|
|
operation: cohorts_staff_recalculate_create
|
|
enabled: false
|
|
cohorts-staff-stuck-retrieve:
|
|
operation: cohorts_staff_stuck_retrieve
|
|
enabled: false
|
|
cohorts-update:
|
|
operation: cohorts_update
|
|
enabled: false
|
|
cohorts-used-in-retrieve:
|
|
operation: cohorts_used_in_retrieve
|
|
enabled: false
|