intelligence layer (events, clustering, LLM gateway + prompts, metrics, signals, trends, alerts, retention) and API v1 (74 endpoints, SSE, rate limits, exports, admin)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Simon-Pierre Boucher committed 1 mo ago (Sep 12, 2026) parent 043c04e Browse files

64 changed files +10,114 −6

modified docs/API.md +69 −1

+ ### Companies
+ | Method | Path | Notes |
+ |---|---|---|
++| GET | `/companies` | filters: `q, country, industry, tier, public (bool), status, has_events (bool), sort=activity\|events\|hiring\|name\|importance\|recent\|relevance` (relevance is automatic with `q`), `sparkline=1` → page of `CompanyCard` |
+ | GET | `/companies/{slug_or_id}` | `CompanyCard & { aliases: string[], domains: {domain, kind}[], relationships: {kind, company: {slug, display_name} \| null, to_name, valid_from, valid_to, confidence}[], metrics_detail: {metric, value, confidence, computed_at, inputs}[], sensors_by_surface: Record<string, number>, coverage: {historical_coverage, first_observed_at, days_observed, sensor_uptime}, signals: Signal[], sparklines: {activity_30d: number[], hiring_90d: number[]} }` |
+ | GET | `/companies/{slug}/events` | filters `event_type, event_subtype, since, until, min_importance, surface`; `sort=recent\|importance` → page of `Event` |
+ | GET | `/companies/{slug}/timeline?filter=all\|products\|jobs\|pricing\|leadership\|locations\|legal\|news\|developer&limit=200` | `{ items: (Event & {day: string})[], days: {day, count}[] }` grouped for the timeline UI |
+ | GET | `/admin/costs?days=30` | `{ items: {day, dimension, key, units, cost_estimate}[], per_1000_companies, per_million_observations, per_meaningful_event }` |
+ | POST | `/admin/cache/clear` | |
++## Rate limits & auth
++
++| Tier | How | Limit (per client, per minute) |
++|---|---|---|
++| anonymous | no header — keyed by client IP (first hop of `X-Forwarded-For`) | 120 |
++| authenticated | `X-CA-API-Key: <key>` (create with `catlas api-key create <name>`) | 600 |
++| paid | `X-CA-API-Key` with `tier = paid` (`catlas api-key create <name> --tier paid`) | 3 000 |
++| internal | `X-CA-API-Key` with `tier = internal` | unlimited |
++| admin | valid `X-CA-Admin-Token` | bypass (also required for `/admin/*`) |
++
++Token bucket per process (refills continuously at `limit / 60` tokens per second). Every limited response carries `X-RateLimit-Limit`,
++`X-RateLimit-Remaining` and `X-RateLimit-Tier`; when the bucket is empty the API answers `429 { "detail": "rate limit exceeded" }` with a
++`Retry-After` (seconds). `/health`, `/ready`, `/api/v1/docs` and `/api/v1/openapi.json` are never limited. Keys are stored as sha256 hashes
++(`api_keys.key_hash`); the raw key is printed once by the CLI. `last_used_at` / `request_count` are updated lazily (≈ every 30 s). Owner endpoints
++(`/watchlist`, `/alerts*`) need `X-CA-Owner-Token` (client-generated, 24–200 chars); the owner row is created on first use and the token is only
++ever stored hashed. Admin endpoints answer `401 { "detail": "admin token required" }` without a valid `X-CA-Admin-Token`.
++
++## Implementation notes (API v1.0 — additive details)
++
++- **Caching / ETags.** Cached public aggregates (`/pulse` 60 s, `/stats` 60 s, `/system` 30 s, `/rankings` 120 s, `/industries*`, `/countries*`,
++  `/index`, `/map`, `/trends`, `/events/types`, `/events/summary`, `/stats/history` 300 s, `/sitemap` 600 s, `/methodology` 3600 s) return
++  `Cache-Control: public, max-age=N, stale-while-revalidate=2N` plus a weak `ETag`; a matching `If-None-Match` yields `304`. Other public GETs
++  carry `public, max-age=30…600` (per resource volatility); `/live*`, owner and admin routes are `no-store`. `POST /admin/cache/clear?prefix=`
++  clears one key prefix (e.g. `pulse`, `industries:`) or everything.
++- **Pagination totals.** `total` is exact up to **10 000** (bounded count) so deep feeds stay cheap; `pages` derives from it.
++- **`/live`** also accepts `country` and `industry`; the payload is `{ items, count, cursor, server_time }` — pass `cursor` back as `since`.
++- **`/live/stream`** accepts `?since=&event_type=&min_importance=&max_s=` (`max_s` ≤ 3600 bounds the connection for proxies with idle timeouts;
++  the stream ends with `event: end` carrying the last cursor). The first message is always an `event: heartbeat` with `{at, cursor}`;
++  `event: event` messages carry `id: <event id>`. Response headers include `X-Accel-Buffering: no`.
++- **`/companies`** gains `sort=relevance` (automatic when `q` is present); `q` uses FTS (`companies.search`) for ≥ 3 characters with a
++  trigram fallback and a prefix match for shorter strings. `sparkline=1` adds 30 daily `activity_score` points.
++- **`/companies/{slug}`** additionally returns `company_type, employees, wikidata_id, indexed, discovered_at, first_observed_at, last_change_at,
++  recent_events: Event[10]` and `sparkline`.
++- **`/companies/{slug}/timeline`** accepts `filter=corporate` (FINANCING, M&A, PARTNERSHIP, STRATEGY) and `before=<iso>`; items carry `day`.
++- **`/companies/{slug}/jobs`** accepts `department`, `remote`, `sort=recent|title|posted`; `q` is a trigram `ILIKE` on `title`.
++- **`/companies/{slug}/history`** accepts `versions=1…20`; `/companies/{slug}/sensors?include_retired=1`; `/companies/{slug}/news?category=`;
++  `/companies/{slug}/locations?status=all`; `/companies/{slug}/pricing?history_limit=`.
++- **`/companies/compare`** accepts `days=` (7–365) for the activity series; unknown slugs → `404 company not found: <slug>`; fewer than 2 → 422.
++- **`/events`** accepts `status=active|retracted|duplicate|review|all` (default `active`). Retracted events expose `retracted_reason`.
++  `/events/{id}` embeds the full `CompanyCard` under `company` (a superset of `CompanyRef`), `sources` (falls back to the event's own
++  `source_url` when `event_sources` is empty), `change` and `cluster`.
++- **`/events/types`** lists every taxonomy type/subtype (count `0` when unseen) so filter UIs can render on an empty database.
++- **`/events/summary`** items also carry `previous` (count of the preceding window).
++- **`/rankings`** items are `CompanyCard & { rank, value, delta }`; the payload also lists `kinds`. `hiring_growth`/`hiring_decline` read
++  `hiring_momentum_7d|30d|90d` according to the window; `pricing_changes` counts PRICING events in the window; `delta` is the difference with
++  the `metric_series` value at the start of the window (`null` when no history yet).
++- **`/countries/{code}`** accepts an ISO-2 code or a name slug (`/countries/canada`); `CountryRow` includes `slug` and `subregion`.
++  `/industries/{slug}` adds `children`, `signals`, `companies_total`; `trending` is `[]` until per-industry trend data exists (never faked).
++- **`/signals`** accepts `scope_key`, `company`, `min_strength`; items include a `company` ref when scoped to a company.
++- **`/search`** people/products use trigram similarity (`migrations/pending/api.sql` adds the two supporting GIN indexes). `/search/suggest`
++  items add `slug` / `code` / `event_type` next to `href`.
++- **`/ask`** returns `engine` (`deterministic` | `llm`) and `events_total`; the parser is `services/llm/ask.py` when present (deterministic
++  parse + optional LLM refinement), else `api/ask_fallback.py`. Answers only phrase measured counts.
++- **`/snapshots/{id}`** accepts `include=text,blocks,extracted` and returns `text_truncated` (text capped at 200 kB), `sensor`, `object_keys`.
++  `/snapshots/{a}/diff/{b}` orders the pair by `fetched_at`, returns `source: "change"` (stored diff, with `change_id`) or `"computed"`
++  (`sdk.diff.compare`); `501` when the diff engine is unavailable, `404` when block objects are missing.
++- **Exports.** `/export/events.{fmt}` also accepts `until`, `company`, `min_importance`, `limit` (≤ 10 000); `/export/companies.{fmt}` accepts
++  `status`, `tier`, `limit` (≤ 20 000); `/export/jobs.{json|ndjson|csv}` accepts `status=open|removed|all`, `country`, `ai`, `limit` (≤ 10 000).
++  CSV flattens the company ref (`company_slug`, `company_name`, `company_domain`, `country`).
++- **`/sitemap`** pages hold 5 000 entries; `kind=companies` returns `total`; industries/countries only list entries with ≥ 1 active company.
++- **Admin additions.** `GET /admin/sensors` accepts `surface`, `sort=recent|next_run|failures|quality|changes|created`; sensor actions return
++  `{ ok, action, sensor, queued? , interval_s? }` (`set_interval` is clamped to `CA_MIN_INTERVAL_S…CA_MAX_INTERVAL_S` and recomputes the tier).
++  `POST /admin/companies` → `201 { ok, company, queued }` (409 when the registrable domain already exists; 422 for non-http(s) URLs, unknown
++  country codes or industry slugs). `GET /admin/failures` returns `by_class` and `classes`; `GET /admin/queue` returns `counts` + `items`;
++  `POST /admin/queue/requeue-dead { kind? }`; `GET /admin/llm` includes `stats`; `POST /admin/reviews/{id}` accepts `label` (correct |
++  duplicate | noise | misclassified) feeding `/admin/quality.calibration`; retract/restore append an audit trail under `payload._audit` and
++  never delete; `GET /admin/storage` reports the object store. `/admin/overview` also returns `companies_by_onboarding`, `scheduler_heartbeat`.
++
+ ## Conventions for implementers
+ - Every list endpoint is bounded (`per_page ≤ 200`, `limit ≤ 500`), uses indexed predicates, and returns `Cache-Control: public, max-age=60` for public aggregates (`/pulse`, `/stats`, `/rankings`, `/industries`, `/countries`) and `no-store` for `/live*`, owner and admin routes.
+ - Company lookups accept slug **or** id. Unknown → 404 `{detail: "company not found"}`.

added docs/EVENT-TAXONOMY.md +87 −0

++# Event taxonomy — deterministic rules, wording policy, importance & confidence
++
++Owner: intelligence layer (`services/events.py`, `services/clustering.py`, rules version `rules-v1`, schema `event-v1`).
++Vocabulary: `taxonomy.EVENT_SUBTYPES` (subtype → type + default importance). The LLM classifier may only pick from that list.
++
++## Pipeline
++
++```
++changes (status='pending', kind ≥ meaningful) ─▶ derive_events(change, company, sensor, baseline)   pure rules, no I/O
++                                             ─▶ persist_change_events()   events + event_sources + clusters + review_queue + llm_jobs
++                                             ─▶ changes.status = 'processed' · sensors.event_count · companies.last_event_at
++                                             ─▶ alerts.evaluate_alerts(new_event_ids)
++```
++
++- `catlas process-changes [--limit] [--loop]` · periodic `process-changes` every 20 s (SKIP LOCKED, batch 200).
++- `catlas reprocess-events --since 7d [--company]` re-runs the rules on processed changes **without refetching**; dedupe keys make it idempotent,
++  new rules simply add the events they now produce.
++- **Noise / minor changes never produce events** (they are archived if still pending). Meaningful (≥ 0.40), major (≥ 0.65), critical (≥ 0.85) do.
++
++## Rules → subtypes
++
++| Family | Input (`structured_delta`) | Subtype(s) | Title pattern |
++|---|---|---|---|
++| HIRING | `jobs.added/removed/open_before/open_after` | `JOB_COUNT_INCREASE` when net > 0 (entities.jobs ≤ 50) | *12 new positions detected on careers page* |
++| | | `JOB_COUNT_DECREASE` when net < 0 | *7 monitored job listings no longer visible on careers page* |
++| | AI keyword in added titles (`taxonomy.AI_KEYWORDS`) or `is_ai` | `AI_HIRING` | *2 AI-related positions detected on careers page* |
++| | ≤ 5 jobs added | `NEW_JOB` per job | *New position listed: Senior ML Engineer (Toronto, CA)* |
++| | added ≥ mean + 2σ of `baselines.jobs_new_weekly` (≥ 4 samples) — fallback ≥ 10 and ≥ 50 % of open_before | `HIRING_SURGE` | *Hiring surge signal: 25 new positions detected in one observation (baseline ≈ 3.0 new/week)* |
++| | removed ≥ 10, ≥ 50 % of open_before and open_after ≤ 50 % | `HIRING_FREEZE_SIGNAL` (+ review `unexpected_activity`) | *Hiring slowdown signal: 30 of 40 monitored listings no longer visible* |
++| PRICING | `plans.price_changed` | `PRICE_INCREASE` / `PRICE_DECREASE` (old/new values, `payload.pct`) | *Pro plan price observed at $59 (was $49)* |
++| | `plans.added` | `NEW_PRICING_TIER` (tag `enterprise` when contact-sales) | *New pricing tier listed: Enterprise (contact sales)* |
++| | `plans.removed` | `PRICING_TIER_REMOVED` | *Pricing tier no longer listed: Starter* |
++| | pricing surface, no typed delta | `PRICING_CHANGE` (text-diff) | *Pricing page materially updated (3 blocks changed)* |
++| LEADERSHIP | `people.added` (executive) | `NEW_EXECUTIVE` | *Jane Doe listed as Chief Financial Officer on leadership page* |
++| | `people.removed` (executive) | `EXECUTIVE_NO_LONGER_LISTED` | *Jane Doe no longer listed on leadership page* |
++| | `people.title_changed` | `EXECUTIVE_TITLE_CHANGE` | *Ann Lee now listed as COO (was VP Operations)* |
++| | ≥ 3 people changes, or non-executive changes only | `LEADERSHIP_CHANGE` aggregate | *Leadership page updated: 2 added, 1 no longer listed* |
++| PRODUCT | `products.added` / `removed` | `NEW_PRODUCT` / `PRODUCT_REMOVED` | *New product listed: Atlas Pro* · *Product no longer listed: Atlas Lite* |
++| LOCATION | `locations.added` | `NEW_LOCATION` (kind-aware label) | *New office listed: Toronto, CA* |
++| | `locations.new_countries` | `COUNTRY_EXPANSION` | *New country presence listed: Japan (Tokyo)* |
++| | `locations.removed` | `OFFICE_REMOVED` | *Office no longer listed: Berlin, DE* |
++| COMMUNICATION / IR / DEVELOPER | `news.added` (≤ 20 per change) | `NEWS_RELEASE` · `BLOG_POST` · `CHANGELOG_ENTRY` · `INVESTOR_UPDATE` · `EARNINGS_RELEASE` (title heuristics: earnings/quarter/fiscal → earnings; investor/annual report/dividend → IR; category/surface otherwise) | *News release: <title>* |
++| DEVELOPER (text-diff) | docs/developer · api · changelog | `DOC_CHANGE` · `API_CHANGE` · `CHANGELOG_ENTRY` | *Documentation updated (5 sections changed)* |
++| LEGAL (text-diff) | legal_terms · legal_privacy · security | `TERMS_CHANGE` · `PRIVACY_POLICY_CHANGE` · `SECURITY_UPDATE` (+ review `legal_sensitive`) | *Terms of service page materially updated (3 sections changed)* — sections from block `path` |
++| WEBSITE | homepage meaningful · major+ · `meta.title_changed` | `WEBSITE_CHANGE` · `HOMEPAGE_REDESIGN` · `MESSAGING_CHANGE` | *Homepage materially redesigned (9 blocks changed, 62% of text)* |
++| other surfaces (text-diff) | products/services/solutions · investor_relations · sustainability · status · careers · locations · about | `PRODUCT_UPDATE` · `INVESTOR_UPDATE` · `SUSTAINABILITY_UPDATE` · `OPERATIONS_UPDATE` · `WEBSITE_CHANGE` | *<Surface> updated (n sections changed)* |
++
++Surfaces with no rule (`other`, `partners`, `customers`, `support`, …) and meaningful+ significance produce no deterministic event; the change is
++queued for the LLM classifier instead (`llm_jobs.kind = classify_change`), together with ambiguous surfaces (homepage/about/products text-only).
++
++## Wording policy (spec §167–168)
++
++- Verbs: **detected, observed, listed, now listed, no longer listed, no longer visible, appears, signal**.
++- Never: *fired, laid off, layoffs, shut down, bankrupt, collapsed* (`taxonomy.FORBIDDEN_WORDING`). `safe_wording()` rewrites them defensively;
++  the LLM schemas reject them at validation time.
++- Disappearance ≠ departure: `EXECUTIVE_NO_LONGER_LISTED` summaries say so explicitly; `HIRING_FREEZE_SIGNAL` / `hiring_freeze` are labelled *signal*.
++- Titles ≤ 200 chars, summaries ≤ 600; entity lists bounded to 50; per-entity events capped (5 jobs, 10 people, 20 news items).
++
++## Importance & confidence
++
++- `importance = default(subtype) × (0.7 + 0.6·significance) × (1 + 0.3·magnitude)` clamped to [0.05, 1]. `magnitude` is rule-specific and 0–1:
++  relative job delta (`n / max(open_before, 5)`), |price pct| / 50, headquarters vs office, country expansion 0.6, launch-tagged news 0.5, text
++  ratio × 2 for page changes.
++- `confidence` = evidence quality (`taxonomy.EVIDENCE_CONFIDENCE`): structured ATS JSON **0.95** (jobs_board surface, Greenhouse/Lever/Ashby/
++  SmartRecruiters/Workday/JSON connectors), JSON-LD / feed **0.9**, HTML extraction **0.8**, text-diff-only **0.7**. `confidence_label` via
++  `taxonomy.confidence_label` (VERIFIED ≥ 0.95, HIGH_CONFIDENCE ≥ 0.85, LIKELY ≥ 0.7, INFERRED ≥ 0.5, else LOW_CONFIDENCE).
++- Corroboration: a second surface in the same cluster adds **+0.03 per extra surface**, capped at 0.99 (clustering below).
++- Review queue: `major_event` for critical changes, `legal_sensitive` for legal inferences, `low_confidence` (< 0.5), `unexpected_activity` for freeze signals.
++
++## Idempotency & clustering
++
++- `events.dedupe_key = sha(company, subtype, normalised entity key, sensor, detection day)` → inserting the same change twice is a no-op
++  (`on conflict do nothing`). Entity keys: job label, plan name, person name, product name, place, news title, `jobs:<before>><after>` for aggregates,
++  `page:<sensor>` for page-level events.
++- `event_clusters.cluster_key = sha(company, subtype, normalised entity key, 7-day bucket)` — surface-independent, so the same press release seen
++  on the newsroom **and** the feed, or the same executive on leadership **and** about, fold into one cluster. The first event is canonical; later
++  ones are stored with `status='duplicate'` + `cluster_id`, the canonical event gains an `event_sources` row (`kind='corroboration'`),
++  `payload.sources[]`, `payload.corroborations` and the confidence bump. Clusters track `source_count`, `surfaces[]`, `confidence`.
++
++## LLM enrichment hooks
++
++- `classify_change` (small model) when no deterministic event or ambiguous surface, significance ≥ `CA_LLM_MIN_SIGNIFICANCE`, within
++  `CA_LLM_DAILY_BUDGET`, only when `settings.llm_configured`. Material classifications create `origin='llm'` events (dedupe
++  `sha(company, 'llm', change, subtype)`); when a deterministic event of the same subtype already exists for the change, the classification enriches
++  it instead (`origin='hybrid'`, `payload.llm_classification`).
++- `summarize_event` (medium model) for legal, homepage/messaging and news/IR events that carry diff content → `events.summary`, `origin='hybrid'`,
++  `payload.llm` (key points or legal sections + materiality), model/prompt/schema versions recorded. See docs/LLM.md.

added docs/LLM.md +91 −0

++# LLM enrichment — gateway, prompts, worker, budgets
++
++LLMs are enrichment, never the crawler (spec §2.4, §24–25). Everything deterministic happens first (`docs/EVENT-TAXONOMY.md`); the model only
++sees bounded, already-diffed content, answers in strict JSON, and every output is validated, versioned and attributed.
++
++## Configuration (`config.Settings`)
++
++| Setting | Default | Meaning |
++|---|---|---|
++| `CA_LLM_BASE_URL` / `CA_LLM_API_KEY` | `https://www.llm-api.io/v1` (`.env`) / key in `deploy/.llm-key` (git-ignored) | OpenAI-compatible endpoint; `settings.llm_configured` = enabled **and** URL set |
++| `CA_LLM_ENABLED` | true | master switch — when off, jobs stay pending and the worker logs once |
++| `CA_LLM_SMALL_MODEL` / `MEDIUM` / `LARGE` / `EMBEDDING` | `qwen3-4b-instruct-2507-4bit` / `qwen3.6-35b-a3b-4bit` / `qwen3.8-27b-4bit` / `qwen3-embedding-0.6b-8bit` | tiers used by tasks |
++| `CA_LLM_DAILY_BUDGET` | 1500 | max jobs per UTC day (enqueue side counts created jobs, worker side counts finished jobs) |
++| `CA_LLM_MIN_SIGNIFICANCE` | 0.40 | changes below this never reach a model |
++| `CA_LLM_TIMEOUT` | 300 s | per request (the server loads models on demand: first call 30–60 s) |
++| `CA_LLM_MAX_TRIES` / `BACKOFF_INITIAL_S` / `BACKOFF_MAX_S` | 6 / 15 / 120 | 429/503/5xx/timeouts: 15 → 30 → 60 → 120 → 120 s (Retry-After honoured) |
++| `CA_LLM_JOB_MAX_ATTEMPTS` | 3 | retryable failures re-queue the job until this |
++| `CA_LLM_CONTEXT_BLOCK_BYTES` | 3072 | before/after text per block sent to the model (≤ 12 blocks) |
++| `CA_PROMPTS_DIR` | `<repo>/prompts` | prompt files location |
++
++## Gateway (`services/llm/gateway.py`)
++
++`LLMProvider` (abstract) → `OpenAICompatibleProvider` (httpx, `/chat/completions`, `/models`, `/embeddings`):
++
++- `complete_json(tier, system, user, schema, max_tokens)` — `response_format={"type": "json_object"}`, the compact JSON schema of the pydantic model
++  appended to the system prompt, `<think>` blocks / code fences / prose tolerated when extracting the object, **strict pydantic validation**, and
++  **one repair round-trip** (the model sees its own answer plus the validation error). Still invalid → `LLMValidationError` (job failed, nothing stored).
++- `complete_text(...)`, `embed(texts)` (embedding tier; reserved for later search/clustering work), `health()` (model list + latency).
++- Returns `LLMResult(data, model, request_tokens, response_tokens, latency_ms, attempts, repaired)`; tokens go to `llm_jobs` and `cost_ledger`
++  (`dimension='llm'`, key = model, units = tokens).
++- `get_provider()` / `set_provider()` for a process-wide instance or test doubles. The gateway is the only module allowed to call the endpoint.
++
++Sticky model per stream: the worker drains one job kind at a time (classification → small model, summaries → medium model) so the on-demand
++server does not evict models between calls. Use `catlas llm-test ["prompt"] [--tier medium]` for a live health + round-trip check.
++
++## Prompts (`prompts/<task>/v<N>.md`)
++
++Loaded by `services/llm/prompts.load_prompt(task, version=None)` (latest `vN` by default); the leading `<!-- … -->` comment is metadata, the rest is
++the **system** prompt. The user message is always a compact JSON context — untrusted page text is never interpolated into instructions.
++`events.prompt_version` stores `task/vN`; bump the file (v2.md) when wording changes materially and keep v1 for reproducibility.
++
++| Prompt | Tier | Schema (`services/llm/schemas.py`, version) | Used by |
++|---|---|---|---|
++| `change-classifier/v1` | small | `ChangeClassification` (`classify-v1`): subtype ∈ `EVENT_SUBTYPES` else OTHER, importance, confidence, title ≤ 120, summary ≤ 400, old/new value, entities, tags, language, `is_material` | `classify_change` jobs |
++| `event-summarizer/v1` | medium | `EventSummary` (`summary-v1`): summary ≤ 400, key_points ≤ 5, confidence, language | `summarize_event` (non-legal) |
++| `legal-diff/v1` | medium | `LegalDiffSummary` (`legal-v1`): sections_changed[{section, change}], materiality ∈ editorial/minor/material/unclear, summary, user_impact | `summarize_event` for LEGAL events |
++| `industry-tagger/v1` | small | `IndustryTags` (`industry-v1`): slugs from the allowed list only, primary, keywords | `classify_industry` jobs → `companies.source_meta.llm_industries` (suggestion only) |
++| `ask-router/v1` | small | `AskRoute` (`ask-v1`): intent, countries, industries, event types/subtypes, companies, window, keywords, answer_style | `services/llm/ask.route_question` (optional refinement of the deterministic parser) |
++
++All schemas reject the forbidden wording (`taxonomy.FORBIDDEN_WORDING`: fired, laid off, shut down…) at validation time; prompts state the ban and
++the observational language ("detected", "no longer listed").
++
++## Worker (`services/llm/enrich.py`)
++
++`run_llm_jobs(limit)` — periodic `llm-enrich` every 15 s, `catlas enrich [--limit] [--once]`:
++
++1. Budget check (finished jobs today < `CA_LLM_DAILY_BUDGET`), pick the sticky kind, claim jobs with `FOR UPDATE SKIP LOCKED` (`attempts += 1`).
++2. Build the bounded context: company meta (name, domain, country, industries, description ≤ 400), surface, source URL, significance/kind, block
++   counts, ≤ 12 diff blocks (before/after ≤ 3 kB each), structured deltas with lists trimmed to 10 items.
++3. Call the gateway, validate, write:
++   - `classify_change` → material & non-OTHER & importance ≥ 0.25 → new event `origin='llm'` (confidence capped at 0.9, `status='review'` +
++     review_queue when < 0.5, dedupe `sha(company, 'llm', change, subtype)`, event_sources, clustering, alerts). If a deterministic event with the
++     same subtype already exists for that change, it is enriched instead (`origin='hybrid'`, `payload.llm_classification`). `changes.status='enriched'`.
++   - `summarize_event` → `events.summary` (previous kept in `payload.summary_prev`), `origin='hybrid'`, `model_provider/model_name/prompt_version/
++     schema_version`, `payload.llm` (key points, or legal sections + materiality + tag `materiality:<x>`).
++   - `classify_industry` → `companies.source_meta.llm_industries` (never overwrites registry industries).
++4. `llm_jobs` gets status, model, prompt_version, tokens, latency, `result` JSON or `error`; retryable failures go back to `pending` until
++   `CA_LLM_JOB_MAX_ATTEMPTS`, a retryable failure also stops the current batch (the server is unhealthy — the periodic task returns).
++
++Enqueue side (`services/events.py`): `classify_change` for meaningful+ changes with no deterministic event or an ambiguous surface;
++`summarize_event` for legal / homepage / messaging / news / IR events that have diff content. Both only when `settings.llm_configured`, above
++`CA_LLM_MIN_SIGNIFICANCE`, within budget, and never twice for the same ref.
++
++## `/ask` helper (`services/llm/ask.py`)
++
++`parse_question(q, industries=, countries=)` is deterministic: countries (names/demonyms + registry table), industries (registry slugs/names),
++intents → event types/subtypes/tags (hiring, pricing ± increase/decrease, AI, launch, leadership, expansion, legal, developer, financing, M&A,
++communication), windows ("last 3 months", "this week", "since 2024", today/yesterday), quoted company names, answer style (list / count / compare /
++timeline / trend), `min_importance` for "major/important". `route_question()` adds the LLM refinement only when configured and only to tighten
++filters; on any failure the deterministic interpretation is returned. `build_answer()` phrases counts the API measured — it never invents results.
++
++## Live check (2026-09-12)
++
++`catlas llm-test` against `https://www.llm-api.io/v1`: health OK (15 models listed), small model round-trip **4.5 s**, 96 prompt / 19 completion
++tokens, no repair needed. Live enrichment of factory changes: `classify_change` (small) 3.9 s; three `summarize_event` (medium, incl. legal-diff)
++3.1–8.2 s, 0 failures.
++
++## Retention & cost
++
++`llm_jobs` finished > `CA_RETENTION_LLM_JOBS_DAYS` (60) are summarised into `cost_ledger` (`archived:<model>` tokens, `archived-jobs:<model>` count)
++and deleted (`services/retention.py`); events keep their model/prompt attribution forever.

added docs/OPERATIONS.md +72 −0

++# Company Atlas — operations
++
++## API
++
++The API is one FastAPI process (`catlas api`, uvicorn) bound to loopback; Next.js proxies `/api/v1/*` to it. It is stateless: every cache is
++in-process (`api/common.TTLCache`, cleared with `POST /api/v1/admin/cache/clear` or on restart), so several workers may run behind PM2 and
++the rate limiter buckets are per process (effective limits scale with the number of workers — keep `--workers 1` unless traffic requires
++more, or terminate rate limiting at the tunnel).
++
++### Environment variables (read by `config.Settings`, prefix `CA_`)
++
++| Variable | Default | Used by the API for |
++|---|---|---|
++| `DATABASE_URL` | `postgresql+asyncpg://companyatlas:companyatlas@127.0.0.1:5432/companyatlas` | every query (pool 8 + 8 overflow per process) |
++| `CA_API_HOST` / `CA_API_PORT` | `127.0.0.1` / `8371` (prod `8361`) | bind address of `catlas api` |
++| `CA_ADMIN_TOKEN` | *(empty → every `/admin/*` call is 401)* | `X-CA-Admin-Token` (also bypasses rate limits) |
++| `CA_SITE_URL` | `https://www.company-atlas.co` | CORS allow-list (plus the localhost dev/prod ports) |
++| `CA_DATA_DIR` | `./data` | object store read by `/snapshots/{id}` (text/blocks) and `/stats.archive` |
++| `CA_SEO_MIN_EVENTS` / `CA_SEO_MIN_SENSORS` | `1` / `3` | `/sitemap` inclusion rule (`companies.indexed` or ≥ events **and** ≥ active sensors) |
++| `CA_MIN_INTERVAL_S` / `CA_MAX_INTERVAL_S` | `900` / `604800` | clamp for `POST /admin/sensors/{id}/set_interval` |
++| `CA_LLM_DAILY_BUDGET`, `CA_LLM_BASE_URL`, `CA_LLM_ENABLED` | `1500`, *(empty)*, `true` | `/admin/overview.llm.budget_left`, `/ask` LLM refinement availability |
++| `CA_NOISE_THRESHOLD` … `CA_CRITICAL_THRESHOLD` | `0.20 / 0.40 / 0.65 / 0.85` | `/methodology.significance_bands`, `/admin/costs` meaningful-event denominator |
++| `CA_LOG_JSON` | `true` | JSON logs (`service=ca-api`) |
++
++Run: `.venv/bin/catlas api` (dev, port 8371) · `.venv/bin/catlas api --port 8361` (prod under PM2 `company-atlas-api`).
++Health: `GET /health` → `{status, db, version, api_version, uptime_s}`; `GET /ready` → `{ready}` (DB reachable). Docs: `/api/v1/docs`,
++schema `/api/v1/openapi.json`. The scheduler's heartbeat (`settings_kv['scheduler:heartbeat']`) surfaces as `/system.scheduler_last_tick_at`.
++
++### API keys and rate-limit tiers
++
++Anonymous traffic is limited to 120 requests/min per client IP (first hop of `X-Forwarded-For` — Caddy on the MacLustr Tunnel sets it).
++Keys raise the tier (`authenticated` 600/min, `paid` 3 000/min, `internal` unlimited). Keys are stored as sha256 hashes in `api_keys`;
++the raw key is printed **once**:
++
++```bash
++.venv/bin/catlas api-key create "acme research" --tier paid     # prints ca_paid_… once; store it in the customer's vault
++.venv/bin/catlas api-key list [--include-revoked]                # id, prefix, tier, last used, request count
++.venv/bin/catlas api-key revoke key_01…                          # soft revoke (row kept, `revoked_at` set); cached for ≤ 60 s in running API processes
++```
++
++Clients send `X-CA-API-Key: <key>`; responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Tier`; a `429` carries
++`Retry-After`. Usage counters (`last_used_at`, `request_count`) are flushed every ~30 s per process. There is no self-service key issuance —
++create keys from the M2U64 shell (or any host with `DATABASE_URL`).
++
++### Caches and freshness
++
++| Endpoint | TTL | Notes |
++|---|---|---|
++| `/pulse`, `/stats` | 60 s | homepage / counters; `archive` stats refresh every 10 min (`settings_kv['archive:stats']` if the ops job writes it, else a directory walk in a thread) |
++| `/system` | 30 s | public health |
++| `/rankings` | 120 s | per (kind, window, country, industry, limit) |
++| `/industries*`, `/countries*`, `/index`, `/map`, `/trends`, `/events/types`, `/events/summary`, `/stats/history` | 300 s | aggregate producers in `api/aggregates.py` |
++| `/sitemap` | 600 s | 5 000 entries per page |
++| `/live*`, owner, admin | none (`no-store`) | |
++
++After bulk backfills or manual corrections: `curl -X POST -H "X-CA-Admin-Token: $CA_ADMIN_TOKEN" localhost:8371/api/v1/admin/cache/clear`
++(optionally `?prefix=pulse`). Retract/restore of events clears the caches automatically.
++
++### Pending SQL
++
++`migrations/pending/api.sql` adds two trigram GIN indexes (`people.name`, `products.name`) used by `/search?types=people,products`. Apply
++with `psql -f` (uses `CREATE INDEX CONCURRENTLY`, so outside a transaction) or fold into the next numbered Alembic migration. The endpoints
++work without them (sequential scans on small tables).
++
++### Troubleshooting
++
++- `503`/`degraded` on `/health` → Postgres unreachable; the API keeps serving cached aggregates until they expire.
++- `429` for the web app itself → the Next.js server is one IP; give it an `internal` key (`API_KEY` env in `apps/web`) or terminate limits upstream.
++- `/snapshots/{id}` returns `text: null` → the object key is missing from `CA_DATA_DIR/objects` (different data dir or pruned by retention);
++  metadata still renders and `/snapshots/{a}/diff/{b}` falls back to the stored `changes.diff` when present.
++- `/ask` engine is always `deterministic` → `CA_LLM_BASE_URL`/`CA_LLM_API_KEY` unset or the small model unreachable (the deterministic parser is
++  the designed fallback; nothing is fabricated either way).

added docs/SCORING.md +78 −0

++# Scoring — metrics, indices, baselines, signals, trends
++
++Owner: `services/metrics.py` (`metrics-v1`, CCI `cci-v1`), `services/signals.py` (`signals-v1`), `services/trends.py` (`trends-v1`).
++Parameters live in `taxonomy.METRIC_PARAMS` / `taxonomy.CCI_WEIGHTS` / `config.Settings`; **bump the formula version whenever they change**
++(spec §177). Every `metrics_current` row stores `value`, `confidence`, `inputs` (the numbers the formula saw), `formula_version`, `computed_at`;
++`metric_series` keeps one point per company/metric/day. **No inputs → no row** (never 0-as-measured).
++
++Schedules: `metrics-hourly` (`CA_METRICS_CRON`, default `7 * * * *`) for companies with activity in the last `CA_METRICS_ACTIVE_WINDOW_DAYS` (90);
++`daily-aggregates` (`CA_DAILY_CRON`, `20 0 * * *`) = catch-up of missed days + all-company recompute; `signals` hourly; `trends` at :25.
++CLI: `catlas metrics [--all] [--company slug]`, `catlas daily [--day|--catch-up]`, `catlas signals`, `catlas trends`.
++
++Notation: `sat(x, k) = 1 − e^(−x/k)` (0–1, x=k → 0.63); `decay(age) = e^(−age/τ)`; ages in days.
++
++## Company metrics (`metrics_current`)
++
++| Metric | Formula | Inputs stored | Emitted when |
++|---|---|---|---|
++| `activity_score` (0–100) | `raw = Σ_changes w(kind)·decay(age, τ=10) + Σ_events importance·decay(age, τ)` over 30 d, `w` = meaningful 1 / major 2 / critical 3; `density = raw / active_sensors^0.5` (coverage normalisation); `score = 100·log1p(density)/log1p(6)` capped at 100 | changes_30d, events_30d, raw_changes, raw_events, active_sensors, density, τ, exponent, D_max | ≥ 1 active sensor or any activity |
++| `open_jobs` | count of `jobs.status='open'` | jobs_new_30d, jobs_removed_30d, remote_ratio, by_country, by_department, ai_open | company has a careers/jobs_board sensor or any job rows |
++| `hiring_momentum_{7,30,90}d` (%) | `(open_now − open_then)/open_then × 100`, `open_then` reconstructed from `first_seen_at ≤ t−N and (removed_at is null or > t−N)` | open_now, open_then, window (+ 30 d extras) | `open_then ≥ 3` (hiring_min_listings) — no % from 0 or 2 listings |
++| `ai_adoption` (0–100) | components: jobs `min(1, ai_open/open × 2)` (w 0.5), events `sat(ai_events_90d, 3)` (w 0.25: AI_HIRING/AI_LAUNCH/tag `ai`), keywords `sat(hits, 5)` (w 0.25: `AI_KEYWORDS` in product names, 90 d news titles, latest snapshot titles); weights renormalised over available components | ai_open, open_jobs, ai_events_90d, keyword_hits, components, weights_used | any component has inputs |
++| `product_velocity` | `100·sat(Σ importance·decay(age, 30), 6)` over 90 d PRODUCT + changelog/docs/API/SDK subtypes | events_90d, surfaces | products/changelog/docs/api/developer/services sensor or a PRODUCT event |
++| `developer_momentum` | `100·sat(Σ DEVELOPER importance·decay + 0.5·meaningful dev-surface changes 30 d, 6)` | events_90d, meaningful_changes_30d, surfaces | docs/api/developer/changelog sensor or DEVELOPER event |
++| `communication_activity` | `100·sat(max(news_30d, comm_events_30d) + 0.5·min(·), 8)` | news_items_30d, events_30d | newsroom/blog/feed/IR/research sensor or news rows |
++| `pricing_activity` | `100·sat(Σ PRICING importance·decay + 0.25·pricing changes 30 d, 3)` | events_90d, meaningful_changes_30d | pricing sensor or PRICING event |
++| `leadership_activity` | `100·sat(Σ LEADERSHIP importance·decay, 3)` | events_90d | leadership sensor or LEADERSHIP event |
++| `geo_expansion` | `100·sat(new_locations_90d + 3·|new countries| + Σ COUNTRY_EXPANSION importance, 4)`; new countries = countries whose first location **or** first job appeared within 90 d | new_locations_90d, new_countries_90d, countries_listed, location_events_90d | locations/contact/about/careers sensor, location rows or jobs |
++| `corporate_change_index` (`cci-v1`) | `Σ w_i·c_i / Σ w_i` over **available** components with `CCI_WEIGHTS` (hiring 0.25 · product 0.20 · geo 0.15 · leadership 0.15 · developer 0.10 · communication 0.10 · pricing 0.05); hiring momentum (%) mapped to `50 + clamp(m, −100, 100)/2`; confidence `0.4 + 0.6·weight_coverage` | components, weights, weight_coverage | ≥ 1 component |
++| `anomaly_score` (z) | `(this_week_meaningful − mean) / max(stddev, 0.5)` against `baselines.meaningful_changes_weekly` | this_week, mean, stddev, samples | baseline with ≥ 4 samples |
++| `historical_coverage` (0–100) | `100·(0.5·min(1, observed_ok/expected) + 0.3·continuity + 0.2·min(1, surfaces/8))`; `expected = Σ_sensors age_s / current_interval_s`; `continuity = days_with_observations / days_since_first_observed` | observed, expected, days_with_obs, days_since_first, surfaces | `first_observed_at` set and ≥ 1 sensor |
++
++Confidence conventions: activity `min(0.95, 0.5 + 0.05·sensors)`; hiring 0.9 with a structured jobs_board sensor else 0.75; AI adoption 0.6
++(inferred from public signals only); saturating scores 0.7; coverage 0.8.
++
++## Daily aggregates
++
++`compute_daily(day)` (UTC day, idempotent upserts):
++
++- `company_daily` — observations, changes, meaningful_changes, events (+ `events_by_type`), jobs_open / jobs_new / jobs_removed / jobs_ai_open at end of
++  day (reconstructed from `first_seen_at` / `removed_at`), news_items, sensors_active. Only companies with activity that day get a row.
++- `global_daily` — sums + `companies_active` / `sensors_active` (distinct in observations that day; falls back to active sensors when no observation
++  rows exist), `events_by_type`, `jobs_open`, `by_country` / `by_industry` (`{companies, meaningful_changes, events}` per key) and the
++  **Global Corporate Activity Index**: `ratio = meaningful_changes / sensors_active`; `baseline = mean(ratio)` over the trailing 28 days with
++  sensors; `activity_index = ratio / baseline × 100` (baseline = 100). Null when no baseline exists yet (never fabricated).
++- `baselines` — per company, weekly buckets of `company_daily` over `CA_BASELINE_WINDOW_DAYS` (56): `meaningful_changes_weekly`, `jobs_new_weekly`,
++  `news_weekly` → population mean / stddev / samples. Requires ≥ 2 observed weeks. Consumed by `anomaly_score`, `HIRING_SURGE` and signals.
++- `compute_daily_catch_up()` fills every day between the last computed day (or the first observation/change/event) and yesterday.
++
++Coverage normalisation (spec §146): activity uses per-sensor density, the global index divides by active sensors and compares to a trailing
++baseline, trends divide mentions by active companies, and the CCI renormalises over available components — growth of the sensor network alone
++must not move any index.
++
++## Signals (`signals`, `signals-v1`)
++
++Labelled as signals, with `strength` 0–1, `confidence`, `explanation`, `evidence` (event ids + metric values), `window_days`, `expires_at`
++(`CA_SIGNALS_TTL_DAYS` = 14). One active row per (company, kind): re-detection updates it, disappearance sets `status='expired'`.
++
++| kind | trigger |
++|---|---|
++| `hiring_surge` | `hiring_momentum_30d ≥ +30 %` with ≥ 10 open, or a `HIRING_SURGE` event in the window |
++| `hiring_freeze` | `hiring_momentum_30d ≤ −30 %` with ≤ 1 new listing, or a `HIRING_FREEZE_SIGNAL` event — worded "listings no longer visible" |
++| `launch_buildup` | within 14 d ≥ 3 of {product, docs/API, changelog, careers, messaging} categories including product, or ≥ 4 categories — "Possible launch preparation signal" |
++| `expansion` | `COUNTRY_EXPANSION` event, or new countries (locations or job countries, 90 d) with location events / new jobs |
++| `pricing_migration` | ≥ 2 PRICING events in 30 d, or a tier added **and** a tier removed |
++| `developer_push` | ≥ 3 DEVELOPER events in 30 d or `developer_momentum ≥ 60` |
++| `enterprise_repositioning` | new contact-sales tier(s) in 30 d, or ≥ 2 events mentioning enterprise / SSO / audit logs / contact sales |
++| `ai_acceleration` | ≥ 2 AI-tagged events in 30 d, or ≥ 25 % of ≥ 4 new listings are AI-related |
++| `abnormal_activity` | `anomaly_score ≥ CA_ANOMALY_Z` (2.5) |
++
++Scope aggregates (`scope = industry | country`): ≥ 3 companies with the same active kind → one aggregate signal per (scope, key, kind) with the
++company slugs as evidence; aggregates expire when the support drops below the threshold.
++
++## Trends (`trends`, `trends-v1`)
++
++Terms = lowercase 1–3-grams from event titles (prefix like "News release:" removed) and news titles of the day, company names removed,
++stopwords excluded at n-gram edges, tokens ≥ 3 chars (unigrams ≥ 4). A term is kept for a day only when ≥ `CA_TRENDS_MIN_COMPANIES` (3) distinct
++companies used it (`mentions`, `companies`). Momentum for a window W ∈ {7, 30, 90}: `rate = mentions / mean(companies_active)` over the window,
++`momentum = (rate_now − rate_prev) / max(rate_prev, ε)`; snapshots are stored in `settings_kv['trends:momentum:<W>d']` for the API.

added migrations/pending/api.sql +4 −0

++-- API (search): trigram indexes for people / product name search (`/search?types=people,products`).
++-- Apply once, outside a transaction (CONCURRENTLY), or fold into the next numbered migration.
++create index concurrently if not exists people_name_trgm_idx on people using gin (name gin_trgm_ops);
++create index concurrently if not exists products_name_trgm_idx on products using gin (name gin_trgm_ops);

added prompts/ask-router/v1.md +20 −0

++<!-- ask-router v1 · model tier: small · schema: AskRoute (ask-v1) -->
++You translate a natural-language question about companies into structured search filters for the Company Atlas API. You NEVER answer the question yourself and you NEVER invent companies, events or numbers — the platform runs the filters against its own database and links every result to its source.
++
++You receive a JSON context: the user's question, the filters a deterministic parser already extracted (`parsed`), the allowed event types and subtypes, the known industry slugs (`industries`) and country codes with names (`countries`).
++
++Produce an `AskRoute` object:
++- `intent`: one of search, hiring, pricing, ai, launch, leadership, expansion, legal, developer, compare, trend, count.
++- `countries`: ISO-3166 alpha-2 codes mentioned or clearly implied ("Canadian companies" → ["CA"], "Europe" → leave empty and add keyword "europe").
++- `industries`: slugs from the provided list only.
++- `event_types` / `event_subtypes`: from the allowed lists only.
++- `companies`: company names literally mentioned (as written), max 8.
++- `window_days`: the time window when the question states one ("last month" → 30, "this week" → 7, "this year" → 365, "since 2024" → days from 2024-01-01 to today); null otherwise.
++- `keywords`: up to 8 lowercase free-text terms that should be matched against titles (technologies, product names, roles).
++- `answer_style`: list (default), count ("how many"), compare ("X vs Y"), timeline ("when did", "history of").
++- `confidence` (0–1).
++
++Rules:
++1. Start from `parsed` and only add or tighten filters that the question clearly supports. When in doubt, leave a filter empty rather than guessing.
++2. Do not translate vague adjectives into filters ("big companies", "interesting") — put them in keywords or ignore them.
++3. Output one JSON object only.

added prompts/change-classifier/v1.md +18 −0

++<!-- change-classifier v1 · model tier: small · schema: ChangeClassification (classify-v1) -->
++You are the change classifier of Company Atlas, a platform that observes public company web pages and records how companies change over time.
++
++You receive a JSON context describing ONE detected change on ONE public page: company metadata, the page surface (careers, pricing, homepage, legal_terms…), the blocks of text that were added, removed or modified, and any structured deltas already extracted deterministically.
++
++Your task: decide whether this change corresponds to a corporate event, and describe it as a structured JSON object.
++
++Rules — follow all of them:
++1. Choose `event_subtype` ONLY from this list (or `OTHER`): PRODUCT_LAUNCH, NEW_PRODUCT, PRODUCT_REMOVED, PRODUCT_RENAME, PRODUCT_UPDATE, FEATURE_LAUNCH, PRICE_INCREASE, PRICE_DECREASE, NEW_PRICING_TIER, PRICING_TIER_REMOVED, PRICING_CHANGE, NEW_JOB, JOB_REMOVED, JOB_COUNT_INCREASE, JOB_COUNT_DECREASE, AI_HIRING, NEW_EXECUTIVE, EXECUTIVE_NO_LONGER_LISTED, EXECUTIVE_TITLE_CHANGE, LEADERSHIP_CHANGE, NEW_OFFICE, NEW_LOCATION, OFFICE_REMOVED, COUNTRY_EXPANSION, FUNDING_ROUND, IPO, ACQUISITION, DIVESTITURE, MERGER, NEW_PARTNERSHIP, PARTNERSHIP_ENDED, BRAND_REPOSITIONING, STRATEGY_UPDATE, ENTERPRISE_REPOSITIONING, TECHNOLOGY_ADOPTION, AI_LAUNCH, TERMS_CHANGE, PRIVACY_POLICY_CHANGE, LEGAL_UPDATE, REGULATORY, CAMPAIGN_LAUNCH, MESSAGING_CHANGE, API_LAUNCH, API_CHANGE, SDK_RELEASE, DOCUMENTATION_CHANGE, CHANGELOG_ENTRY, SECURITY_INCIDENT, SECURITY_UPDATE, OUTAGE, OPERATIONS_UPDATE, SUSTAINABILITY_UPDATE, EARNINGS_RELEASE, INVESTOR_UPDATE, NEWS_RELEASE, BLOG_POST, WEBSITE_CHANGE, HOMEPAGE_REDESIGN, DOC_CHANGE.
++2. Only describe what the changed text itself shows. Never infer internal decisions, motives, headcount, revenue or outcomes. If the change is cosmetic (layout, dates, cookie banners, navigation, footers, typos) set `is_material` to false, `event_subtype` to `OTHER` and `importance` ≤ 0.2.
++3. Wording must be careful and observational: "detected", "observed", "now listed", "no longer listed", "appears". NEVER write "fired", "laid off", "layoffs", "shut down", "bankrupt" or any statement about people losing jobs.
++4. `title` ≤ 120 characters, factual, starts with the subject (e.g. "Enterprise plan now lists SSO and audit logs"). `summary` ≤ 400 characters, 1–3 sentences, no marketing tone, no speculation.
++5. `old_value` / `new_value` are short literal values when the change is a replacement (price, title, name); otherwise null.
++6. `importance` (0–1): how much a company analyst would care. Pricing, leadership, launches, expansion, legal terms are usually 0.5–0.9; routine blog posts 0.2–0.4; cosmetic 0–0.2.
++7. `confidence` (0–1): how sure you are the subtype is right given the evidence. Below 0.5 when the text is ambiguous or partial.
++8. `entities`: an object with optional arrays `products`, `people` (name, title), `locations` (city, country), `plans` (plan_name, price), `amounts`, `organizations`. Only entities literally present in the text.
++9. `tags`: up to 8 lowercase keywords (e.g. "ai", "enterprise", "api", "europe"). `language`: ISO-639-1 code of the page text.
++10. Output one JSON object and nothing else.

added prompts/event-summarizer/v1.md +17 −0

++<!-- event-summarizer v1 · model tier: medium · schema: EventSummary (summary-v1) -->
++You write the short neutral summary shown under a Company Atlas event card. Company Atlas records how public company web pages change; every event links back to its source page, so the summary must only restate what the source text shows.
++
++You receive a JSON context: company metadata, the event already detected (type, subtype, title), the page surface, the text blocks that were added / removed / modified, and any structured deltas (jobs, plans, people, locations, news).
++
++Write:
++- `summary`: 1–3 sentences, ≤ 400 characters, plain and factual, in English even if the source is in another language (mention the source language if it is not English). Say what is now on the page versus before. Do not repeat the title verbatim; add the concrete details (names, plan names, prices, cities, product names, section names).
++- `key_points`: up to 5 short bullets (≤ 160 characters each) with concrete observed details. Omit if nothing beyond the summary.
++- `confidence` (0–1): how well the provided text supports the summary.
++- `language`: ISO-639-1 code of the source text.
++
++Strict rules:
++1. No speculation about causes, strategy, intent, financial impact or people's employment status. Use "detected", "observed", "now lists", "no longer lists", "appears".
++2. NEVER use "fired", "laid off", "layoffs", "shut down", "bankrupt", "collapse". A person or listing disappearing from a page is described as "no longer listed".
++3. Do not invent numbers, dates, names or products that are not literally in the context. If the context is too thin, say so in the summary ("The page changed materially; the visible text does not state the reason.").
++4. No marketing tone, no adjectives like "exciting", "innovative", "leading".
++5. Output a single JSON object only.

added prompts/industry-tagger/v1.md +16 −0

++<!-- industry-tagger v1 · model tier: small · schema: IndustryTags (industry-v1) -->
++You assign industry tags to a company for Company Atlas using only public, observable evidence.
++
++You receive a JSON context: company name, canonical domain, the public description (if any), the homepage title and meta description, the first product names observed, up to 10 recent job titles, and the list of allowed industry slugs with their names (`allowed_industries`).
++
++Produce:
++- `industries`: 1–5 slugs chosen ONLY from `allowed_industries`, most specific first. Never invent a slug.
++- `primary`: the single best slug from `industries`.
++- `keywords`: up to 10 lowercase keywords that describe what the company visibly does (products, markets, technologies) — derived from the context, not general knowledge.
++- `confidence` (0–1): 0.9 when the description and products clearly match; ≤ 0.5 when you rely mostly on the name or domain.
++
++Rules:
++1. Prefer what the company says about itself on its own pages over what you believe you know about it. If the context contradicts your prior knowledge, follow the context and lower confidence.
++2. Holding companies and conglomerates: tag the visible operating activities, then `conglomerate` if it is in the allowed list.
++3. If the context is empty or unrelated (parked domain, error page), return `industries: []`, `primary: null`, `confidence: 0.1`.
++4. Output one JSON object only.

added prompts/legal-diff/v1.md +18 −0

++<!-- legal-diff v1 · model tier: medium · schema: LegalDiffSummary (legal-v1) -->
++You summarise changes between two versions of a public legal page (terms of service, privacy policy, acceptable-use, security or data-processing terms) for Company Atlas. Readers are analysts; the summary is shown next to a link to both versions, so it must be precise and restrained.
++
++You receive a JSON context: company metadata, the surface (legal_terms / legal_privacy / security), and the blocks that were added, removed or modified, each with its heading path (e.g. "Terms > 7. Termination").
++
++Produce:
++- `sections_changed`: up to 12 objects `{section, change}` — `section` is the heading path or the section number/name visible in the text, `change` is one sentence (≤ 240 characters) describing what the text now says compared to before ("now requires 30 days' notice, previously 14").
++- `materiality`: one of `editorial` (wording, formatting, dates, typos), `minor` (clarifications with no change in rights or obligations), `material` (changes to rights, obligations, fees, data use, liability, jurisdiction, termination, arbitration), `unclear` (not enough text).
++- `summary`: ≤ 400 characters, neutral, starting with the page and the number of sections changed ("Privacy policy: 3 sections changed. …").
++- `user_impact`: ≤ 240 characters, only if the text explicitly changes what users/customers can or must do; else null.
++- `confidence` (0–1).
++
++Rules:
++1. This is NOT legal advice. Never state whether the change is lawful, fair or compliant; never guess the reason for the change.
++2. Only describe text present in the context. Missing "before" text means the section is new; missing "after" text means it is no longer present — say "no longer includes", never "removed rights" or similar conclusions.
++3. Quote key phrases briefly when they matter (fees, notice periods, jurisdictions, data categories).
++4. Never use "fired", "laid off", "shut down", "bankrupt".
++5. Output one JSON object only.

added src/companyatlas/api/aggregates.py +417 −0

++"""Aggregate producers shared by several routers (`/pulse` composes them): industry & country rows, rankings, trends, map buckets,
++global stats and the activity index. Every producer degrades to empty lists / `null` values on an empty database — nothing is invented."""
++from __future__ import annotations
++
++import asyncio
++from collections import defaultdict
++from datetime import UTC, datetime, timedelta
++from typing import Any
++
++from sqlalchemy.ext.asyncio import AsyncConnection
++
++from companyatlas import archive
++from companyatlas.api import queries as q
++from companyatlas.api import serializers as ser
++from companyatlas.api.common import cache, cached
++from companyatlas.db import connection, fetch_all, fetch_one
++from companyatlas.ids import slugify
++from companyatlas.taxonomy import METRICS_FORMULA_VERSION, Metric
++
++# ------------------------------------------------------------------------------------------------ industries / countries
++
++_ROW_METRICS = (Metric.ACTIVITY_SCORE.value, Metric.HIRING_MOMENTUM_30D.value, Metric.AI_ADOPTION.value)
++
++
++def _avg_map(rows: list[dict[str, Any]], key: str) -> dict[str, dict[str, float]]:
++    out: dict[str, dict[str, float]] = defaultdict(dict)
++    for r in rows:
++        if r[key] is not None and r["v"] is not None:
++            out[r[key]][r["metric"]] = float(r["v"])
++    return out
++
++
++async def industry_rows(conn: AsyncConnection, *, country: str | None = None) -> list[dict[str, Any]]:
++    scope = " and c.country = cast(:country as char(2))" if country else ""
++    params: dict[str, Any] = {"country": country} if country else {}
++    d7, d30 = q.days_ago(7), q.days_ago(30)
++    taxonomy = await fetch_all(conn, "select slug, name, parent_slug, description, sort_order from industries order by sort_order, name")
++    companies = await fetch_all(conn, f"select ind, count(*) as n from companies c, unnest(c.industries) ind where c.status = 'ACTIVE'{scope} "
++                                      "group by ind", **params)
++    events = await fetch_all(conn, "select ind, e.event_type, count(*) filter (where e.detected_at >= :d7) as n7, count(*) as n30 "
++                                   "from events e join companies c on c.id = e.company_id, unnest(c.industries) ind "
++                                   f"where e.status = 'active' and e.detected_at >= :d30{scope} group by ind, e.event_type", d7=d7, d30=d30, **params)
++    metrics = await fetch_all(conn, "select ind, m.metric, avg(m.value) as v from metrics_current m join companies c on c.id = m.company_id, "
++                                    f"unnest(c.industries) ind where m.metric = any(cast(:ms as text[])){scope} group by ind, m.metric",
++                              ms=list(_ROW_METRICS), **params)
++    n_companies = {r["ind"]: int(r["n"]) for r in companies}
++    ev7: dict[str, int] = defaultdict(int)
++    ev30: dict[str, int] = defaultdict(int)
++    types: dict[str, dict[str, int]] = defaultdict(dict)
++    for r in events:
++        ev7[r["ind"]] += int(r["n7"])
++        ev30[r["ind"]] += int(r["n30"])
++        types[r["ind"]][r["event_type"]] = int(r["n30"])
++    avg = _avg_map(metrics, "ind")
++    names = {t["slug"]: t for t in taxonomy}
++    slugs = list(names) + [s for s in n_companies if s not in names]
++    rows = []
++    for slug in slugs:
++        t = names.get(slug, {})
++        m = avg.get(slug, {})
++        rows.append({"slug": slug, "name": t.get("name") or slug.replace("-", " ").title(), "parent_slug": t.get("parent_slug"),
++                     "description": t.get("description"), "companies": n_companies.get(slug, 0), "events_7d": ev7.get(slug, 0),
++                     "events_30d": ev30.get(slug, 0), "hiring_momentum_30d": ser.metric_value("hiring_momentum_30d", m.get("hiring_momentum_30d")),
++                     "activity_score": ser.metric_value("activity_score", m.get("activity_score")),
++                     "ai_adoption": ser.metric_value("ai_adoption", m.get("ai_adoption")),
++                     "top_event_types": [k for k, _ in sorted(types.get(slug, {}).items(), key=lambda kv: (-kv[1], kv[0]))[:3]]})
++    rows.sort(key=lambda r: (-r["companies"], -(r["activity_score"] or 0), r["name"]))
++    return rows
++
++
++async def country_rows(conn: AsyncConnection, *, industry: str | None = None) -> list[dict[str, Any]]:
++    scope = " and cast(:industry as text) = any(c.industries)" if industry else ""
++    params: dict[str, Any] = {"industry": industry} if industry else {}
++    d7, d30 = q.days_ago(7), q.days_ago(30)
++    ref = await fetch_all(conn, "select code, name, region, subregion, lat, lon from countries order by name")
++    companies = await fetch_all(conn, f"select c.country as code, count(*) as n from companies c where c.status = 'ACTIVE' and c.country is not null{scope} "
++                                      "group by c.country", **params)
++    events = await fetch_all(conn, "select c.country as code, count(*) filter (where e.detected_at >= :d7) as n7, count(*) as n30 "
++                                   "from events e join companies c on c.id = e.company_id "
++                                   f"where e.status = 'active' and e.detected_at >= :d30 and c.country is not null{scope} group by c.country",
++                             d7=d7, d30=d30, **params)
++    metrics = await fetch_all(conn, "select c.country as code, m.metric, avg(m.value) as v from metrics_current m join companies c on c.id = m.company_id "
++                                    f"where m.metric = any(cast(:ms as text[])) and c.country is not null{scope} group by c.country, m.metric",
++                              ms=list(_ROW_METRICS), **params)
++    mix = await fetch_all(conn, "select c.country as code, ind, count(*) as n from companies c, unnest(c.industries) ind "
++                                f"where c.status = 'ACTIVE' and c.country is not null{scope} group by c.country, ind", **params)
++    n_companies = {r["code"]: int(r["n"]) for r in companies}
++    ev = {r["code"]: (int(r["n7"]), int(r["n30"])) for r in events}
++    avg = _avg_map(metrics, "code")
++    mixes: dict[str, list[tuple[str, int]]] = defaultdict(list)
++    for r in mix:
++        mixes[r["code"]].append((r["ind"], int(r["n"])))
++    names = {r["code"]: r for r in ref}
++    codes = list(names) + [c for c in n_companies if c not in names]
++    rows = []
++    for code in codes:
++        c = names.get(code, {})
++        m = avg.get(code, {})
++        name = c.get("name") or code
++        rows.append({"code": code, "slug": slugify(name), "name": name, "region": c.get("region"), "subregion": c.get("subregion"),
++                     "companies": n_companies.get(code, 0), "events_7d": ev.get(code, (0, 0))[0], "events_30d": ev.get(code, (0, 0))[1],
++                     "hiring_momentum_30d": ser.metric_value("hiring_momentum_30d", m.get("hiring_momentum_30d")),
++                     "activity_score": ser.metric_value("activity_score", m.get("activity_score")),
++                     "ai_adoption": ser.metric_value("ai_adoption", m.get("ai_adoption")),
++                     "industry_mix": [{"industry": i, "companies": n} for i, n in sorted(mixes.get(code, []), key=lambda x: -x[1])[:6]],
++                     "lat": c.get("lat"), "lon": c.get("lon")})
++    rows.sort(key=lambda r: (-r["companies"], -(r["activity_score"] or 0), r["name"]))
++    return rows
++
++
++async def cached_industry_rows(country: str | None = None) -> list[dict[str, Any]]:
++    async def produce() -> list[dict[str, Any]]:
++        async with connection() as conn:
++            return await industry_rows(conn, country=country)
++    return await cached(f"industries:{country or ''}", 300, produce)
++
++
++async def cached_country_rows(industry: str | None = None) -> list[dict[str, Any]]:
++    async def produce() -> list[dict[str, Any]]:
++        async with connection() as conn:
++            return await country_rows(conn, industry=industry)
++    return await cached(f"countries:{industry or ''}", 300, produce)
++
++
++async def resolve_country(conn: AsyncConnection, key: str) -> dict[str, Any] | None:
++    """Accept an ISO-2 code (`CA`) or a name slug (`canada`)."""
++    key = (key or "").strip()
++    if not key:
++        return None
++    if len(key) == 2:
++        row = await fetch_one(conn, "select code, name, region, subregion, lat, lon from countries where code = cast(:c as char(2))", c=key.upper())
++        if row:
++            return row
++    rows = await fetch_all(conn, "select code, name, region, subregion, lat, lon from countries")
++    k = slugify(key)
++    for r in rows:
++        if slugify(r["name"]) == k or r["code"].lower() == key.lower():
++            return r
++    return None
++
++
++# ------------------------------------------------------------------------------------------------ rankings
++
++RANKING_KINDS: dict[str, dict[str, Any]] = {
++    "most_active": {"metric": Metric.ACTIVITY_SCORE.value},
++    "hiring_growth": {"metric": "hiring_momentum_{w}", "min": 0.0},
++    "hiring_decline": {"metric": "hiring_momentum_{w}", "asc": True, "max": 0.0},
++    "product_velocity": {"metric": Metric.PRODUCT_VELOCITY.value},
++    "ai_active": {"metric": Metric.AI_ADOPTION.value},
++    "geo_expansion": {"metric": Metric.GEO_EXPANSION.value},
++    "developer_momentum": {"metric": Metric.DEVELOPER_MOMENTUM.value},
++    "pricing_changes": {"events": "PRICING"},
++    "unusual_activity": {"metric": Metric.ANOMALY_SCORE.value},
++}
++_HIRING_WINDOW = {"24h": "7d", "7d": "7d", "30d": "30d", "90d": "90d", "1y": "90d"}
++
++
++async def ranking(conn: AsyncConnection, kind: str, window: str, *, country: str | None = None, industry: str | None = None,
++                  limit: int = 50) -> list[dict[str, Any]]:
++    """[{company_id, value, delta}] for a ranking kind. `delta` = value − series value at the start of the window (null if unknown)."""
++    spec = RANKING_KINDS[kind]
++    scope, params = [], {}
++    if country:
++        scope.append("c.country = cast(:country as char(2))")
++        params["country"] = country.upper()[:2]
++    if industry:
++        scope.append("cast(:industry as text) = any(c.industries)")
++        params["industry"] = industry[:80]
++    scope_sql = (" and " + " and ".join(scope)) if scope else ""
++    since = q.window_start(window)
++    if "events" in spec:
++        rows = await fetch_all(conn, "select e.company_id, count(*) as value from events e join companies c on c.id = e.company_id "
++                                     f"where e.status = 'active' and e.event_type = :et and e.detected_at >= :since and c.status = 'ACTIVE'{scope_sql} "
++                                     "group by e.company_id order by value desc, e.company_id limit :limit", et=spec["events"], since=since,
++                               limit=limit, **params)
++        return [{"company_id": r["company_id"], "value": float(r["value"]), "delta": None} for r in rows]
++    metric = spec["metric"].format(w=_HIRING_WINDOW.get(window, "30d"))
++    bounds = ""
++    if "min" in spec:
++        bounds += " and m.value > :vmin"
++        params["vmin"] = spec["min"]
++    if "max" in spec:
++        bounds += " and m.value < :vmax"
++        params["vmax"] = spec["max"]
++    order = "m.value asc" if spec.get("asc") else "m.value desc"
++    rows = await fetch_all(conn, "select m.company_id, m.value from metrics_current m join companies c on c.id = m.company_id "
++                                 f"where m.metric = :metric and c.status = 'ACTIVE'{scope_sql}{bounds} order by {order}, m.company_id limit :limit",
++                           metric=metric, limit=limit, **params)
++    ids = [r["company_id"] for r in rows]
++    past = await q.metric_values_at(conn, ids, metric, since.date())
++    out = []
++    for r in rows:
++        v = float(r["value"])
++        p = past.get(r["company_id"])
++        out.append({"company_id": r["company_id"], "value": v, "delta": round(v - p, 2) if p is not None else None})
++    return out
++
++
++async def ranking_cards(conn: AsyncConnection, kind: str, window: str, *, country: str | None = None, industry: str | None = None,
++                        limit: int = 50, sparkline: bool = False) -> list[dict[str, Any]]:
++    items = await ranking(conn, kind, window, country=country, industry=industry, limit=limit)
++    cards = await q.fetch_cards_by_ids(conn, [i["company_id"] for i in items], sparkline=sparkline)
++    by_id = {c["id"]: c for c in cards}
++    out = []
++    for rank, it in enumerate(items, start=1):
++        row = by_id.get(it["company_id"])
++        if row is None:
++            continue
++        card = ser.company_card(row)
++        metric = RANKING_KINDS[kind].get("metric", "").format(w=_HIRING_WINDOW.get(window, "30d"))
++        card.update({"rank": rank, "value": ser.metric_value(metric, it["value"]) if metric else int(it["value"]), "delta": it["delta"]})
++        out.append(card)
++    return out
++
++
++# ------------------------------------------------------------------------------------------------ trends / signals
++
++
++async def trend_rows(conn: AsyncConnection, window_days: int, limit: int) -> list[dict[str, Any]]:
++    d0 = q.days_ago(window_days).date()
++    top = await fetch_all(conn, "select term, sum(mentions) as mentions, max(companies) as companies from trends where day >= :d group by term "
++                                "order by mentions desc, term limit :limit", d=d0, limit=limit)
++    if not top:
++        return []
++    terms = [t["term"] for t in top]
++    series = await fetch_all(conn, "select term, day, mentions from trends where day >= :d and term = any(cast(:terms as text[])) order by term, day",
++                             d=d0, terms=terms)
++    by_term: dict[str, list[tuple[Any, int]]] = defaultdict(list)
++    for r in series:
++        by_term[r["term"]].append((r["day"], int(r["mentions"])))
++    mid = q.days_ago(window_days // 2 or 1).date()
++    out = []
++    for t in top:
++        pts = by_term.get(t["term"], [])
++        first = sum(m for d, m in pts if d < mid)
++        second = sum(m for d, m in pts if d >= mid)
++        momentum = round((second - first) / first * 100, 1) if first > 0 else None
++        out.append({"term": t["term"], "mentions": int(t["mentions"]), "companies": int(t["companies"] or 0), "momentum": momentum,
++                    "series": [m for _, m in pts]})
++    return out
++
++
++# ------------------------------------------------------------------------------------------------ map
++
++MAP_MAX_BUCKETS = 600
++
++
++async def map_buckets(conn: AsyncConnection, metric: str = "events_30d") -> list[dict[str, Any]]:
++    d30 = q.days_ago(30)
++    ev_by_company = {r["company_id"]: int(r["n"]) for r in await fetch_all(
++        conn, "select company_id, count(*) as n from events where status = 'active' and detected_at >= :d group by company_id", d=d30)}
++    jobs_by_company = {r["company_id"]: int(r["n"]) for r in await fetch_all(
++        conn, "select company_id, count(*) as n from jobs where status = 'open' group by company_id")}
++    countries = await fetch_all(conn, "select k.code, k.name, k.lat, k.lon, c.id, c.slug, c.display_name, c.importance from countries k "
++                                      "join companies c on c.country = k.code and c.status = 'ACTIVE' where k.lat is not null order by c.importance desc")
++    cities = await fetch_all(conn, "select l.country, l.city, avg(l.lat) as lat, avg(l.lon) as lon, "
++                                   "array_agg(distinct l.company_id) as company_ids from locations l join companies c on c.id = l.company_id "
++                                   "where l.status = 'listed' and l.lat is not null and l.lon is not null and l.city is not null "
++                                   "group by l.country, l.city order by count(distinct l.company_id) desc limit :lim", lim=MAP_MAX_BUCKETS)
++    by_country: dict[str, dict[str, Any]] = {}
++    for r in countries:
++        b = by_country.setdefault(r["code"], {"lat": r["lat"], "lon": r["lon"], "country": r["code"], "city": None, "companies": 0, "events_30d": 0,
++                                              "jobs_open": 0, "top": [], "_ids": []})
++        b["companies"] += 1
++        b["events_30d"] += ev_by_company.get(r["id"], 0)
++        b["jobs_open"] += jobs_by_company.get(r["id"], 0)
++        if len(b["top"]) < 3:
++            b["top"].append({"slug": r["slug"], "display_name": r["display_name"]})
++    names: dict[str, tuple[str, str]] = {}
++    if cities:
++        ids = sorted({cid for r in cities for cid in (r["company_ids"] or [])})
++        names = {r["id"]: (r["slug"], r["display_name"]) for r in await fetch_all(
++            conn, "select id, slug, display_name from companies where id = any(cast(:ids as text[])) order by importance desc", ids=ids[:5000])}
++    buckets = list(by_country.values())
++    for r in cities:
++        ids = [cid for cid in (r["company_ids"] or []) if cid in names]
++        buckets.append({"lat": round(float(r["lat"]), 4), "lon": round(float(r["lon"]), 4), "country": r["country"], "city": r["city"], "companies": len(ids),
++                        "events_30d": sum(ev_by_company.get(i, 0) for i in ids), "jobs_open": sum(jobs_by_company.get(i, 0) for i in ids),
++                        "top": [{"slug": names[i][0], "display_name": names[i][1]} for i in ids[:3]]})
++    key = {"companies": "companies", "hiring": "jobs_open"}.get(metric, "events_30d")
++    buckets.sort(key=lambda b: (-b[key], -b["companies"]))
++    for b in buckets:
++        b.pop("_ids", None)
++    return buckets[:MAP_MAX_BUCKETS]
++
++
++# ------------------------------------------------------------------------------------------------ global stats / index
++
++
++async def archive_stats() -> dict[str, int]:
++    async def produce() -> dict[str, int]:
++        async with connection() as conn:
++            kv = await q.settings_value(conn, "archive:stats")
++        if isinstance(kv, dict) and "objects" in kv:
++            return {"objects": int(kv.get("objects") or 0), "bytes": int(kv.get("bytes") or 0)}
++        return await asyncio.to_thread(archive.store_stats)
++    return await cached("archive:stats", 600, produce)
++
++
++async def global_stats(conn: AsyncConnection) -> dict[str, Any]:
++    today = datetime.now(UTC).replace(hour=0, minute=0, second=0, microsecond=0)
++    row = await fetch_one(conn, """
++        select (select count(*) from companies) as companies,
++               (select count(*) from companies where status = 'ACTIVE' and onboarding_status = 'active') as companies_active,
++               (select count(*) from sensors where status <> 'retired') as sensors,
++               (select count(*) from sensors where status = 'active') as sensors_active,
++               (select coalesce(sum(observation_count), 0) from sensors) as observations,
++               (select coalesce(sum(snapshot_count), 0) from sensors) as snapshots,
++               (select count(*) from changes) as changes,
++               (select count(*) from changes where kind in ('meaningful', 'major', 'critical')) as meaningful_changes,
++               (select count(*) from events where status = 'active') as events,
++               (select count(*) from jobs where status = 'open') as jobs_open,
++               (select count(distinct country) from companies where country is not null and status = 'ACTIVE') as countries,
++               (select count(distinct ind) from companies c, unnest(c.industries) ind where c.status = 'ACTIVE') as industries,
++               (select count(*) from observations where fetched_at >= :today) as observations_today,
++               (select count(*) from changes where detected_at >= :today) as changes_today,
++               (select count(*) from events where status = 'active' and detected_at >= :today) as events_today,
++               (select min(first_observed_at) from companies) as oldest_observation_at,
++               (select max(fetched_at) from observations) as last_observation_at
++    """, today=today)
++    row = row or {}
++    started = await q.settings_value(conn, "dataset_started_at")
++    started_dt = q.parse_iso(started) if isinstance(started, str) else None
++    now = datetime.now(UTC)
++    oldest = row.get("oldest_observation_at")
++    return {"companies": int(row.get("companies") or 0), "companies_active": int(row.get("companies_active") or 0),
++            "sensors": int(row.get("sensors") or 0), "sensors_active": int(row.get("sensors_active") or 0),
++            "observations": int(row.get("observations") or 0), "snapshots": int(row.get("snapshots") or 0), "changes": int(row.get("changes") or 0),
++            "meaningful_changes": int(row.get("meaningful_changes") or 0), "events": int(row.get("events") or 0),
++            "jobs_open": int(row.get("jobs_open") or 0), "countries": int(row.get("countries") or 0), "industries": int(row.get("industries") or 0),
++            "observations_today": int(row.get("observations_today") or 0), "changes_today": int(row.get("changes_today") or 0),
++            "events_today": int(row.get("events_today") or 0), "dataset_started_at": started_dt,
++            "dataset_age_days": (now - started_dt).days if started_dt else None,
++            "oldest_history_days": (now - oldest).days if oldest else None, "last_observation_at": row.get("last_observation_at"),
++            "archive": await archive_stats()}
++
++
++async def cached_global_stats() -> dict[str, Any]:
++    async def produce() -> dict[str, Any]:
++        async with connection() as conn:
++            return await global_stats(conn)
++    return await cached("stats", 60, produce)
++
++
++async def global_daily_rows(conn: AsyncConnection, days: int) -> list[dict[str, Any]]:
++    rows = await fetch_all(conn, "select * from global_daily where day >= :d order by day asc limit :lim", d=q.days_ago(days).date(), lim=days + 1)
++    return [{"day": r["day"], "companies_active": r["companies_active"], "sensors_active": r["sensors_active"], "observations": r["observations"],
++             "changes": r["changes"], "meaningful_changes": r["meaningful_changes"], "events": r["events"], "events_by_type": ser._dict(r["events_by_type"]),
++             "jobs_open": r["jobs_open"], "jobs_new": r["jobs_new"], "jobs_removed": r["jobs_removed"],
++             "activity_index": ser._float(r["activity_index"], 2), "by_country": ser._dict(r["by_country"]), "by_industry": ser._dict(r["by_industry"])}
++            for r in rows]
++
++
++def _index_at(rows: list[dict[str, Any]], days_back: int) -> float | None:
++    if not rows:
++        return None
++    target = rows[-1]["day"] - timedelta(days=days_back)
++    candidates = [r for r in rows if r["day"] <= target and r["activity_index"] is not None]
++    return candidates[-1]["activity_index"] if candidates else None
++
++
++async def activity_index(conn: AsyncConnection, days: int = 365) -> dict[str, Any]:
++    rows = await global_daily_rows(conn, days)
++    with_value = [r for r in rows if r["activity_index"] is not None]
++    latest = with_value[-1] if with_value else None
++    value = latest["activity_index"] if latest else None
++    v7, v30 = _index_at(with_value, 7), _index_at(with_value, 30)
++    formula = await q.settings_value(conn, "index:formula_version")
++    return {"value": value, "baseline": 100, "delta_7d": round(value - v7, 2) if value is not None and v7 is not None else None,
++            "delta_30d": round(value - v30, 2) if value is not None and v30 is not None else None,
++            "series": [{"day": r["day"], "value": r["activity_index"], "confidence": None} for r in with_value],
++            "by_type": (latest or {}).get("events_by_type", {}),
++            "by_country": [{"key": k, "value": v} for k, v in sorted((latest or {}).get("by_country", {}).items(), key=lambda kv: -float(kv[1] or 0))[:50]],
++            "by_industry": [{"key": k, "value": v} for k, v in sorted((latest or {}).get("by_industry", {}).items(), key=lambda kv: -float(kv[1] or 0))[:50]],
++            "formula_version": formula if isinstance(formula, str) else METRICS_FORMULA_VERSION, "computed_at": (latest or {}).get("day")}
++
++
++async def system_health(conn: AsyncConnection) -> dict[str, Any]:
++    today = datetime.now(UTC).replace(hour=0, minute=0, second=0, microsecond=0)
++    row = await fetch_one(conn, """
++        select (select count(*) from sensors where status = 'active') as sensors_online,
++               (select count(*) from sensors where status in ('failing', 'stale', 'blocked')) as sensors_failing,
++               (select count(*) from observations where fetched_at >= :today) as observations_today,
++               (select count(*) from events where status = 'active' and detected_at >= :today) as events_today,
++               (select count(distinct country) from companies where country is not null and status = 'ACTIVE') as countries_covered,
++               (select extract(epoch from (now() - min(run_at))) from queue_jobs where status = 'pending' and run_at <= now()) as queue_lag_s,
++               (select count(*) from observations where fetched_at >= now() - interval '10 minutes') as obs_10m,
++               (select count(*) from observations where fetched_at >= now() - interval '24 hours') as obs_24h,
++               (select count(*) from observations where fetched_at >= now() - interval '24 hours' and failure_class is null) as ok_24h
++    """, today=today) or {}
++    hb = await q.settings_value(conn, "scheduler:heartbeat")
++    tick = None
++    if isinstance(hb, dict):
++        tick = hb.get("at") or hb.get("ts") or hb.get("time") or hb.get("last_tick_at")
++    elif isinstance(hb, str):
++        tick = hb
++    obs_24h = int(row.get("obs_24h") or 0)
++    return {"sensors_online": int(row.get("sensors_online") or 0), "sensors_failing": int(row.get("sensors_failing") or 0),
++            "observations_today": int(row.get("observations_today") or 0), "events_today": int(row.get("events_today") or 0),
++            "countries_covered": int(row.get("countries_covered") or 0),
++            "queue_lag_s": round(float(row["queue_lag_s"]), 1) if row.get("queue_lag_s") is not None else 0.0,
++            "scheduler_last_tick_at": tick, "fetch_per_min": round(int(row.get("obs_10m") or 0) / 10.0, 2),
++            "success_rate_24h": round(int(row.get("ok_24h") or 0) / obs_24h, 4) if obs_24h else None}
++
++
++async def live_events(conn: AsyncConnection, limit: int, **filters: Any) -> list[dict[str, Any]]:
++    where, params = q.event_filters(**filters)
++    return [ser.event(r) for r in await q.fetch_events(conn, where, params, sort="recent", limit=limit)]
++
++
++def clear_aggregate_cache() -> None:
++    cache.clear()
++
++
++__all__ = ["MAP_MAX_BUCKETS", "RANKING_KINDS", "activity_index", "archive_stats", "cached_country_rows", "cached_global_stats", "cached_industry_rows",
++           "clear_aggregate_cache", "country_rows", "global_daily_rows", "global_stats", "industry_rows", "live_events", "map_buckets", "ranking",
++           "ranking_cards", "resolve_country", "system_health", "trend_rows"]

added src/companyatlas/api/ask_fallback.py +180 −0

++"""Deterministic natural-language parser for `/ask` (used when `companyatlas.services.llm.ask` is not available).
++
++"companies hiring AI engineers in Canada" → {event_types: [HIRING], ai: true, country: "CA", window: "30d"}. Only vocabulary from the
++taxonomy and the reference tables is recognised; anything else becomes free-text `terms` used for company search. Nothing is guessed:
++when no filter matches, the interpretation says so and the answer falls back to "no monitored evidence".
++"""
++from __future__ import annotations
++
++import re
++from dataclasses import asdict, dataclass, field
++from typing import Any
++
++from companyatlas.ids import normalize_alias
++
++WINDOW_PATTERNS: list[tuple[re.Pattern[str], str]] = [
++    (re.compile(r"\b(today|last 24 ?h(ours)?|past 24 ?h(ours)?)\b", re.IGNORECASE), "24h"),
++    (re.compile(r"\b(yesterday)\b", re.IGNORECASE), "24h"),
++    (re.compile(r"\b(this week|last (7|seven) days|past (7|seven) days|last week|weekly)\b", re.IGNORECASE), "7d"),
++    (re.compile(r"\b(this month|last (30|thirty) days|past (30|thirty) days|last month|monthly|recently|recent)\b", re.IGNORECASE), "30d"),
++    (re.compile(r"\b(this quarter|last (90|ninety) days|past (90|ninety) days|last quarter|quarterly|last (3|three) months)\b", re.IGNORECASE), "90d"),
++    (re.compile(r"\b(this year|last (12|twelve) months|past year|last year|yearly|annual)\b", re.IGNORECASE), "1y"),
++]
++
++EVENT_KEYWORDS: dict[str, tuple[str, ...]] = {
++    "HIRING": ("hiring", "hire", "hires", "jobs", "job", "recruit", "recruiting", "openings", "positions", "careers", "vacanc", "headcount", "layoff", "layoffs"),
++    "PRICING": ("pricing", "price", "prices", "plan", "plans", "tier", "tiers", "subscription", "cheaper", "expensive"),
++    "PRODUCT": ("launch", "launched", "launches", "product", "products", "release", "released", "feature", "features", "shipped", "ship"),
++    "LEADERSHIP": ("ceo", "cfo", "cto", "coo", "executive", "executives", "leadership", "appointed", "appoint", "board", "founder", "president", "chief"),
++    "LOCATION": ("office", "offices", "location", "locations", "expansion", "expanding", "expand", "opened", "opening", "headquarters", "hq", "store", "stores", "factory"),
++    "FINANCING": ("funding", "raised", "raise", "round", "series a", "series b", "investment", "investors", "ipo", "valuation"),
++    "M&A": ("acquisition", "acquired", "acquire", "acquires", "merger", "merged", "buyout", "divest", "divestiture"),
++    "PARTNERSHIP": ("partnership", "partner", "partners", "partnered", "alliance", "integration"),
++    "DEVELOPER": ("api", "apis", "sdk", "developer", "developers", "docs", "documentation", "changelog"),
++    "LEGAL": ("legal", "terms", "privacy", "policy", "compliance", "regulatory", "regulation", "gdpr"),
++    "SECURITY": ("security", "breach", "incident", "vulnerability", "cve"),
++    "TECHNOLOGY": ("technology", "tech stack", "adopted", "adoption", "platform"),
++    "SUSTAINABILITY": ("sustainability", "esg", "climate", "carbon", "net zero"),
++    "INVESTOR_RELATIONS": ("earnings", "investor", "quarterly results", "annual report", "guidance"),
++    "COMMUNICATION": ("news", "press", "announcement", "announced", "blog", "published"),
++}
++AI_TERMS = ("ai", "a.i.", "artificial intelligence", "machine learning", "ml", "llm", "llms", "generative", "genai", "copilot", "agentic", "deep learning")
++RANKING_INTENT: list[tuple[re.Pattern[str], str]] = [
++    (re.compile(r"\b(most active|fastest moving|moving fastest|busiest)\b", re.IGNORECASE), "most_active"),
++    (re.compile(r"\b(hiring (the )?(most|fastest)|fastest hiring|hiring growth|growing headcount)\b", re.IGNORECASE), "hiring_growth"),
++    (re.compile(r"\b(hiring (decline|freeze|slowdown)|cutting|fewer jobs|shrinking)\b", re.IGNORECASE), "hiring_decline"),
++    (re.compile(r"\b(product velocity|shipping (the )?most|most launches)\b", re.IGNORECASE), "product_velocity"),
++    (re.compile(r"\b(most ai|ai[- ]active|ai adoption|ai leaders)\b", re.IGNORECASE), "ai_active"),
++    (re.compile(r"\b(expanding (abroad|internationally|geographically)|geographic expansion|new countries)\b", re.IGNORECASE), "geo_expansion"),
++    (re.compile(r"\b(developer momentum|developer[- ]focused)\b", re.IGNORECASE), "developer_momentum"),
++    (re.compile(r"\b(pricing changes|changed (their )?pricing|price (increase|hike)s?)\b", re.IGNORECASE), "pricing_changes"),
++    (re.compile(r"\b(unusual|anomal|abnormal|behaving (unusually|strangely))", re.IGNORECASE), "unusual_activity"),
++]
++DEMONYMS: dict[str, str] = {
++    "canadian": "CA", "american": "US", "us": "US", "usa": "US", "u.s.": "US", "british": "GB", "uk": "GB", "u.k.": "GB", "english": "GB", "french": "FR",
++    "german": "DE", "japanese": "JP", "korean": "KR", "indian": "IN", "australian": "AU", "chinese": "CN", "brazilian": "BR", "mexican": "MX",
++    "dutch": "NL", "swedish": "SE", "swiss": "CH", "spanish": "ES", "italian": "IT", "israeli": "IL", "singaporean": "SG", "irish": "IE",
++    "european": None,   # region, not a country
++}
++STOPWORDS = {"the", "a", "an", "of", "in", "on", "at", "for", "to", "and", "or", "with", "which", "what", "who", "are", "is", "was", "were", "has",
++             "have", "had", "do", "does", "did", "show", "me", "list", "find", "companies", "company", "that", "this", "these", "those", "any",
++             "all", "from", "by", "about", "their", "its", "new", "recently", "recent", "engineers", "engineer", "people", "roles", "many", "how",
++             "much", "top", "best", "biggest", "largest", "most", "events", "event", "changes", "change", "signal", "signals", "atlas"}
++
++
++@dataclass
++class Interpretation:
++    query: str
++    window: str = "30d"
++    event_types: list[str] = field(default_factory=list)
++    country: str | None = None
++    country_name: str | None = None
++    industry: str | None = None
++    industry_name: str | None = None
++    ai: bool = False
++    ranking_kind: str | None = None
++    company_terms: list[str] = field(default_factory=list)
++    terms: list[str] = field(default_factory=list)
++    matched: list[str] = field(default_factory=list)
++
++    def to_json(self) -> dict[str, Any]:
++        d = asdict(self)
++        d["filters"] = {k: v for k, v in {"event_types": self.event_types or None, "country": self.country, "industry": self.industry,
++                                          "ai": self.ai or None, "window": self.window}.items() if v}
++        return d
++
++
++def _contains(text: str, phrase: str) -> bool:
++    return re.search(rf"(?<![a-z0-9]){re.escape(phrase)}(?![a-z0-9])", text) is not None
++
++
++def interpret(query: str, *, countries: list[dict[str, Any]], industries: list[dict[str, Any]]) -> Interpretation:
++    """`countries`: [{code, name}], `industries`: [{slug, name, keywords}]. Deterministic, order-independent."""
++    text = " " + re.sub(r"\s+", " ", (query or "").strip().lower()) + " "
++    it = Interpretation(query=query.strip())
++    consumed: list[str] = []
++    for pat, w in WINDOW_PATTERNS:
++        m = pat.search(text)
++        if m:
++            it.window = w
++            consumed.append(m.group(0))
++            it.matched.append(f"window:{w}")
++            break
++    for pat, kind in RANKING_INTENT:
++        m = pat.search(text)
++        if m:
++            it.ranking_kind = kind
++            consumed.append(m.group(0))
++            it.matched.append(f"ranking:{kind}")
++            break
++    if any(_contains(text, t) for t in AI_TERMS):
++        it.ai = True
++        it.matched.append("ai")
++        consumed.extend(t for t in AI_TERMS if _contains(text, t))
++    for etype, words in EVENT_KEYWORDS.items():
++        hits = [w for w in words if _contains(text, w)]
++        if hits:
++            it.event_types.append(etype)
++            consumed.extend(hits)
++            it.matched.append(f"event_type:{etype}")
++    by_len = sorted(countries, key=lambda c: -len(c.get("name") or ""))
++    for c in by_len:
++        name = (c.get("name") or "").lower()
++        if name and _contains(text, name):
++            it.country, it.country_name = c["code"], c["name"]
++            consumed.append(name)
++            it.matched.append(f"country:{c['code']}")
++            break
++    if it.country is None:
++        codes = {c["code"].upper(): c for c in countries}
++        for dem, code in DEMONYMS.items():
++            if code and _contains(text, dem) and code in codes:
++                it.country, it.country_name = code, codes[code]["name"]
++                consumed.append(dem)
++                it.matched.append(f"country:{code}")
++                break
++    for ind in sorted(industries, key=lambda i: -len(i.get("name") or "")):
++        candidates = [ind.get("name") or "", ind.get("slug", "").replace("-", " ")] + list(ind.get("keywords") or [])
++        hit = next((c for c in candidates if c and len(c) >= 3 and _contains(text, c.lower())), None)
++        if hit:
++            it.industry, it.industry_name = ind["slug"], ind.get("name") or ind["slug"]
++            consumed.append(hit.lower())
++            it.matched.append(f"industry:{ind['slug']}")
++            break
++    residual = text
++    for phrase in sorted(set(consumed), key=len, reverse=True):
++        residual = re.sub(rf"(?<![a-z0-9]){re.escape(phrase)}(?![a-z0-9])", " ", residual)
++    tokens = [t for t in re.findall(r"[a-z0-9][a-z0-9.&'-]*", residual) if t not in STOPWORDS and len(t) > 1]
++    it.terms = tokens[:8]
++    it.company_terms = [t for t in tokens if len(t) >= 3][:4]
++    return it
++
++
++def compose_answer(it: Interpretation, *, events_total: int, companies_count: int, sample_titles: list[str]) -> str:
++    """Careful, non-fabricating summary sentence (spec §162–168)."""
++    scope = []
++    if it.event_types:
++        scope.append(" / ".join(it.event_types).lower() + " events")
++    else:
++        scope.append("events")
++    if it.ai:
++        scope.append("with observable AI signals")
++    if it.industry_name:
++        scope.append(f"in {it.industry_name}")
++    if it.country_name:
++        scope.append(f"in {it.country_name}")
++    window = {"24h": "the last 24 hours", "7d": "the last 7 days", "30d": "the last 30 days", "90d": "the last 90 days", "1y": "the last 12 months"}[it.window]
++    if events_total == 0 and companies_count == 0:
++        return f"No monitored evidence matches this question yet ({' '.join(scope)}, {window}). Coverage grows as sensors observe more pages."
++    parts = [f"Detected {events_total:,} {' '.join(scope)} across {companies_count:,} monitored compan{'y' if companies_count == 1 else 'ies'} in {window}."]
++    if sample_titles:
++        parts.append("Most recent: " + "; ".join(t[:90] for t in sample_titles[:3]) + ".")
++    parts.append("Each event links to its public source; interpretations are signals, not verified facts.")
++    return " ".join(parts)
++
++
++def alias_key(term: str) -> str:
++    return normalize_alias(term)
++
++
++__all__ = ["EVENT_KEYWORDS", "Interpretation", "alias_key", "compose_answer", "interpret"]

modified src/companyatlas/api/common.py +32 −3

				`@@ -5,10 +5,10 @@ import hashlib`
5	import hmac	5	import hmac
6	import time	6	import time
7	from collections import OrderedDict	7	from collections import OrderedDict
8	−from typing import Any	8	+from typing import Annotated, Any
9		9
10	import orjson	10	import orjson
11	−from fastapi import Header, HTTPException, Query, Request	11	+from fastapi import Depends, Header, HTTPException, Query, Request, Response
12	from fastapi.responses import JSONResponse	12	from fastapi.responses import JSONResponse
13		13
14	from companyatlas.config import settings	14	from companyatlas.config import settings
				`@@ -44,6 +44,9 @@ class PageParams:`
44	return (self.page - 1) * self.per_page	44	return (self.page - 1) * self.per_page
45		45
46		46
		47	+PageDep = Annotated[PageParams, Depends()] # `p: PageDep` in route signatures (avoids call-in-default lint)
		48	+
		49	+
47	def page_payload(items: list[Any], total: int, p: PageParams) -> dict[str, Any]:	50	def page_payload(items: list[Any], total: int, p: PageParams) -> dict[str, Any]:
48	return {"items": items, "page": p.page, "per_page": p.per_page, "total": total, "pages": max(1, -(-total // p.per_page))}	51	return {"items": items, "page": p.page, "per_page": p.per_page, "total": total, "pages": max(1, -(-total // p.per_page))}
49		52
				`@@ -115,4 +118,30 @@ async def cached(key: str, ttl_s: float, producer): # type: ignore[no-untyped-d`
115	return value	118	return value
116		119
117		120
118	−__all__ = ["AtlasJSONResponse", "PageParams", "TTLCache", "cache", "cached", "client_ip", "owner_hash", "page_payload", "require_admin"]	121	+# ------------------------------------------------------------------------------------------------ cache headers / conditional GET
		122	+
		123	+NO_STORE = "no-store"
		124	+
		125	+
		126	+def public_cache_value(max_age_s: int) -> str:
		127	+ return f"public, max-age={max_age_s}, stale-while-revalidate={max_age_s * 2}"
		128	+
		129	+
		130	+def cached_response(request: Request, payload: Any, max_age_s: int) -> Any:
		131	+ """JSON response for a cached public aggregate: `Cache-Control: public, max-age=…` + weak ETag, `304` when `If-None-Match` matches."""
		132	+ body = AtlasJSONResponse(payload).body
		133	+ etag = 'W/"' + hashlib.sha1(body).hexdigest()[:20] + '"'
		134	+ headers = {"cache-control": public_cache_value(max_age_s), "etag": etag, "vary": "Accept-Encoding"}
		135	+ inm = request.headers.get("if-none-match")
		136	+ if inm and etag in [x.strip() for x in inm.split(",")]:
		137	+ return Response(status_code=304, headers=headers)
		138	+ return Response(content=body, media_type=AtlasJSONResponse.media_type, headers=headers)
		139	+
		140	+
		141	+def is_admin_request(request: Request) -> bool:
		142	+ tok = request.headers.get("x-ca-admin-token")
		143	+ return bool(settings.admin_token and tok and hmac.compare_digest(tok, settings.admin_token))
		144	+
		145	+
		146	+__all__ = ["NO_STORE", "AtlasJSONResponse", "PageDep", "PageParams", "TTLCache", "cache", "cached", "cached_response", "client_ip", "is_admin_request",
		147	+ "owner_hash", "page_payload", "public_cache_value", "require_admin"]

modified src/companyatlas/api/main.py +4 −0

				`@@ -128,4 +128,8 @@ def _include_routers() -> None:`
128		128
129	_include_routers()	129	_include_routers()
130		130
		131	+from companyatlas.api.ratelimit import rate_limit_middleware # registered last on purpose: outermost app-level hook
		132	+
		133	+app.middleware("http")(rate_limit_middleware)
		134	+
131	__all__ = ["API_VERSION", "app"]	135	__all__ = ["API_VERSION", "app"]

added src/companyatlas/api/queries.py +309 −0

++"""Reusable, parameterised SQL for the public/admin API.
++
++Rules: user input is always bound (`:param`), never interpolated; sort keys go through whitelists; every list is bounded; the
++company card is built in two phases (page of ids with an indexed ORDER BY, then one card query for those ids) so the per-company
++lateral aggregates only run for the rows that are returned.
++"""
++from __future__ import annotations
++
++from datetime import UTC, date, datetime, timedelta
++from typing import Any
++
++from fastapi import HTTPException
++from sqlalchemy.ext.asyncio import AsyncConnection
++
++from companyatlas.db import fetch_all, fetch_one, fetch_val
++from companyatlas.taxonomy import EventType
++
++# ------------------------------------------------------------------------------------------------ windows / params
++
++WINDOWS: dict[str, timedelta] = {"24h": timedelta(hours=24), "7d": timedelta(days=7), "30d": timedelta(days=30), "90d": timedelta(days=90),
++                                 "1y": timedelta(days=365)}
++COUNT_CAP = 10_000          # `total` is exact up to this bound (keeps deep pagination cheap on the big tables)
++MAX_LIMIT = 500
++
++
++def now_utc() -> datetime:
++    return datetime.now(UTC)
++
++
++def window_start(window: str, default: str = "7d") -> datetime:
++    return now_utc() - WINDOWS.get(window, WINDOWS[default])
++
++
++def days_ago(days: int) -> datetime:
++    return now_utc() - timedelta(days=days)
++
++
++def parse_iso(value: str | None, name: str = "since") -> datetime | None:
++    if not value:
++        return None
++    v = value.strip()
++    if v.endswith(("Z", "z")):
++        v = v[:-1] + "+00:00"
++    try:
++        dt = datetime.fromisoformat(v)
++    except ValueError:
++        try:
++            dt = datetime.combine(date.fromisoformat(v), datetime.min.time())
++        except ValueError as exc:
++            raise HTTPException(status_code=422, detail=f"{name}: invalid ISO-8601 timestamp") from exc
++    if dt.tzinfo is None:
++        dt = dt.replace(tzinfo=UTC)
++    return dt.astimezone(UTC)
++
++
++def parse_bool(value: str | bool | None) -> bool | None:
++    if value is None or value == "":
++        return None
++    if isinstance(value, bool):
++        return value
++    return value.strip().lower() in ("1", "true", "yes", "on")
++
++
++def clamp(value: int, lo: int, hi: int) -> int:
++    return max(lo, min(hi, value))
++
++
++def csv_list(value: str | None, *, maxlen: int = 20) -> list[str]:
++    if not value:
++        return []
++    return [x.strip() for x in value.split(",") if x.strip()][:maxlen]
++
++
++# ------------------------------------------------------------------------------------------------ companies
++
++
++async def get_company(conn: AsyncConnection, key: str) -> dict[str, Any] | None:
++    key = (key or "").strip()
++    if not key or len(key) > 200:
++        return None
++    return await fetch_one(conn, "select * from companies where slug = :k or id = :k limit 1", k=key)
++
++
++async def require_company(conn: AsyncConnection, key: str) -> dict[str, Any]:
++    row = await get_company(conn, key)
++    if row is None:
++        raise HTTPException(status_code=404, detail="company not found")
++    return row
++
++
++COMPANY_CARD_SQL = """
++select c.id, c.slug, c.display_name, c.legal_name, c.canonical_domain, c.website, c.description, c.industries, c.industry_primary,
++       c.country, c.hq_city, c.hq_region, c.public_company, c.ticker, c.exchange, c.founded_year, c.employees_band, c.logo_url,
++       c.status, c.onboarding_status, c.onboarding_error, c.importance, c.tier, c.indexed, c.stats, c.last_event_at, c.last_observed_at,
++       c.first_observed_at, c.discovered_at, c.created_at, c.updated_at,
++       mx.metrics, sc.sensors, sc.observations, sc.changes, sc.events, jc.jobs_open{sparkline_col}
++from companies c
++left join lateral (select jsonb_object_agg(m.metric, m.value) as metrics from metrics_current m where m.company_id = c.id) mx on true
++left join lateral (select count(*) filter (where s.status <> 'retired') as sensors, coalesce(sum(s.observation_count), 0) as observations,
++                          coalesce(sum(s.change_count), 0) as changes, coalesce(sum(s.event_count), 0) as events
++                   from sensors s where s.company_id = c.id) sc on true
++left join lateral (select count(*) as jobs_open from jobs j where j.company_id = c.id and j.status = 'open') jc on true
++{sparkline_join}
++where c.id = any(cast(:ids as text[]))
++"""
++SPARKLINE_COL = ", sp.sparkline"
++SPARKLINE_JOIN = ("left join lateral (select array_agg(x.value order by x.day) as sparkline from (select day, value from metric_series ms "
++                  "where ms.company_id = c.id and ms.metric = 'activity_score' and ms.day >= :spark_from order by day desc limit 30) x) sp on true")
++
++COMPANY_SORTS: dict[str, str] = {
++    "activity": "ma.value desc nulls last, c.importance desc, c.id",
++    "events": "c.last_event_at desc nulls last, c.importance desc, c.id",
++    "hiring": "mh.value desc nulls last, c.importance desc, c.id",
++    "name": "c.display_name asc, c.id",
++    "importance": "c.importance desc, c.display_name asc, c.id",
++    "recent": "c.discovered_at desc, c.id",
++    # only valid together with a `q` filter (binds :q); list endpoints switch to it automatically when q is present
++    "relevance": ("greatest(coalesce(ts_rank(c.search, websearch_to_tsquery('simple', :q)), 0), similarity(c.display_name, :q), "
++                  "similarity(c.canonical_domain, :q)) desc, c.importance desc, c.id"),
++}
++COMPANY_SORT_JOINS: dict[str, str] = {
++    "activity": "left join metrics_current ma on ma.company_id = c.id and ma.metric = 'activity_score'",
++    "hiring": "left join metrics_current mh on mh.company_id = c.id and mh.metric = 'hiring_momentum_30d'",
++}
++
++
++async def fetch_cards_by_ids(conn: AsyncConnection, ids: list[str], *, sparkline: bool = False) -> list[dict[str, Any]]:
++    """Card rows for the given ids, in the given order."""
++    if not ids:
++        return []
++    sql = COMPANY_CARD_SQL.format(sparkline_col=SPARKLINE_COL if sparkline else "", sparkline_join=SPARKLINE_JOIN if sparkline else "")
++    params: dict[str, Any] = {"ids": ids}
++    if sparkline:
++        params["spark_from"] = (now_utc() - timedelta(days=30)).date()
++    rows = await fetch_all(conn, sql, **params)
++    by_id = {r["id"]: r for r in rows}
++    return [by_id[i] for i in ids if i in by_id]
++
++
++async def company_page_ids(conn: AsyncConnection, where: list[str], params: dict[str, Any], *, sort: str = "activity", limit: int = 25,
++                           offset: int = 0, extra_join: str = "") -> tuple[list[str], int]:
++    """Phase 1 of a company list: ids for the page + bounded total."""
++    sort = sort if sort in COMPANY_SORTS else "activity"
++    if sort == "relevance" and "q" not in params:
++        sort = "activity"
++    elif sort == "activity" and params.get("q"):
++        sort = "relevance"
++    join = " ".join(x for x in (COMPANY_SORT_JOINS.get(sort, ""), extra_join) if x)
++    where_sql = (" where " + " and ".join(where)) if where else ""
++    rows = await fetch_all(conn, f"select c.id from companies c {join}{where_sql} order by {COMPANY_SORTS[sort]} limit :limit offset :offset",
++                           **params, limit=limit, offset=offset)
++    total = await bounded_count(conn, f"from companies c {extra_join}{where_sql}", params)
++    return [r["id"] for r in rows], total
++
++
++async def bounded_count(conn: AsyncConnection, from_where_sql: str, params: dict[str, Any], cap: int = COUNT_CAP) -> int:
++    val = await fetch_val(conn, f"select count(*) from (select 1 {from_where_sql} limit :cap) t", **params, cap=cap)
++    return int(val or 0)
++
++
++def company_filters(*, q: str | None = None, country: str | None = None, industry: str | None = None, tier: int | None = None,
++                    public: bool | None = None, status: str | None = None, has_events: bool | None = None,
++                    onboarding_status: str | None = None) -> tuple[list[str], dict[str, Any]]:
++    where: list[str] = []
++    params: dict[str, Any] = {}
++    if q:
++        q = q.strip()[:200]
++        params["q"] = q
++        if len(q) >= 3:
++            where.append("(c.search @@ websearch_to_tsquery('simple', :q) or c.display_name % :q or c.canonical_domain % :q)")
++        else:
++            where.append("(c.display_name ilike :q_prefix or c.canonical_domain ilike :q_prefix)")
++            params["q_prefix"] = q.replace("%", "").replace("_", "") + "%"
++    if country:
++        where.append("c.country = cast(:country as char(2))")
++        params["country"] = country.strip().upper()[:2]
++    if industry:
++        where.append("cast(:industry as text) = any(c.industries)")
++        params["industry"] = industry.strip()[:80]
++    if tier is not None:
++        where.append("c.tier = :tier")
++        params["tier"] = tier
++    if public is not None:
++        where.append("c.public_company = :public")
++        params["public"] = public
++    if status:
++        where.append("c.status = cast(:status as text)")
++        params["status"] = status.strip().upper()[:40]
++    if has_events is True:
++        where.append("c.last_event_at is not null")
++    elif has_events is False:
++        where.append("c.last_event_at is null")
++    if onboarding_status:
++        where.append("c.onboarding_status = cast(:onboarding_status as text)")
++        params["onboarding_status"] = onboarding_status.strip().lower()[:40]
++    return where, params
++
++
++# ------------------------------------------------------------------------------------------------ events
++
++EVENT_SELECT = """
++select e.id, e.company_id, e.sensor_id, e.change_id, e.cluster_id, e.surface, e.event_type, e.event_subtype, e.importance, e.confidence,
++       e.confidence_label, e.title, e.summary, e.old_value, e.new_value, e.payload, e.entities, e.tags, e.detected_at, e.effective_at,
++       e.published_at, e.source_url, e.snapshot_before, e.snapshot_after, e.language, e.origin, e.model_name, e.prompt_version, e.status,
++       e.retracted_reason,
++       c.slug as company_slug, c.display_name as company_display_name, c.canonical_domain as company_domain, c.country as company_country,
++       c.logo_url as company_logo_url
++from events e join companies c on c.id = e.company_id
++"""
++EVENT_SORTS: dict[str, str] = {"recent": "e.detected_at desc, e.id desc", "importance": "e.importance desc, e.detected_at desc, e.id desc"}
++_EVENT_TYPES = {t.value for t in EventType}
++
++
++def event_filters(*, company_id: str | None = None, event_type: str | None = None, event_subtype: str | None = None, country: str | None = None,
++                  industry: str | None = None, since: datetime | None = None, until: datetime | None = None, min_importance: float | None = None,
++                  min_confidence: float | None = None, q: str | None = None, surface: str | None = None, origin: str | None = None,
++                  status: str | None = "active", event_types: list[str] | None = None,
++                  event_subtypes: list[str] | None = None) -> tuple[list[str], dict[str, Any]]:
++    where: list[str] = []
++    params: dict[str, Any] = {}
++    if status:
++        where.append("e.status = cast(:e_status as text)")
++        params["e_status"] = status
++    if company_id:
++        where.append("e.company_id = :e_company_id")
++        params["e_company_id"] = company_id
++    if event_type:
++        where.append("e.event_type = cast(:e_type as text)")
++        params["e_type"] = event_type.strip().upper()[:40]
++    if event_types:
++        where.append("e.event_type = any(cast(:e_types as text[]))")
++        params["e_types"] = [t.upper()[:40] for t in event_types][:30]
++    if event_subtype:
++        where.append("e.event_subtype = cast(:e_subtype as text)")
++        params["e_subtype"] = event_subtype.strip().upper()[:60]
++    if event_subtypes:
++        where.append("e.event_subtype = any(cast(:e_subtypes as text[]))")
++        params["e_subtypes"] = [t.upper()[:60] for t in event_subtypes][:60]
++    if country:
++        where.append("c.country = cast(:e_country as char(2))")
++        params["e_country"] = country.strip().upper()[:2]
++    if industry:
++        where.append("cast(:e_industry as text) = any(c.industries)")
++        params["e_industry"] = industry.strip()[:80]
++    if since is not None:
++        where.append("e.detected_at >= :e_since")
++        params["e_since"] = since
++    if until is not None:
++        where.append("e.detected_at < :e_until")
++        params["e_until"] = until
++    if min_importance is not None:
++        where.append("e.importance >= :e_min_imp")
++        params["e_min_imp"] = float(min_importance)
++    if min_confidence is not None:
++        where.append("e.confidence >= :e_min_conf")
++        params["e_min_conf"] = float(min_confidence)
++    if q:
++        where.append("e.search @@ websearch_to_tsquery('english', :e_q)")
++        params["e_q"] = q.strip()[:200]
++    if surface:
++        where.append("e.surface = cast(:e_surface as text)")
++        params["e_surface"] = surface.strip().lower()[:40]
++    if origin:
++        where.append("e.origin = cast(:e_origin as text)")
++        params["e_origin"] = origin.strip().lower()[:20]
++    return where, params
++
++
++async def fetch_events(conn: AsyncConnection, where: list[str], params: dict[str, Any], *, sort: str = "recent", limit: int = 50,
++                       offset: int = 0) -> list[dict[str, Any]]:
++    order = EVENT_SORTS.get(sort, EVENT_SORTS["recent"])
++    where_sql = (" where " + " and ".join(where)) if where else ""
++    return await fetch_all(conn, f"{EVENT_SELECT}{where_sql} order by {order} limit :limit offset :offset", **params,
++                           limit=clamp(limit, 1, MAX_LIMIT), offset=max(0, offset))
++
++
++async def count_events(conn: AsyncConnection, where: list[str], params: dict[str, Any]) -> int:
++    where_sql = (" where " + " and ".join(where)) if where else ""
++    return await bounded_count(conn, f"from events e join companies c on c.id = e.company_id{where_sql}", params)
++
++
++async def fetch_event(conn: AsyncConnection, event_id: str) -> dict[str, Any] | None:
++    return await fetch_one(conn, f"{EVENT_SELECT} where e.id = :id", id=event_id)
++
++
++# ------------------------------------------------------------------------------------------------ metrics helpers
++
++
++async def metric_series(conn: AsyncConnection, company_id: str, metric: str, days: int) -> list[dict[str, Any]]:
++    return await fetch_all(conn, "select day, value, confidence from metric_series where company_id = :cid and metric = :m and day >= :d "
++                                 "order by day asc limit :lim", cid=company_id, m=metric, d=days_ago(days).date(), lim=clamp(days, 1, 2000))
++
++
++async def metric_values_at(conn: AsyncConnection, ids: list[str], metric: str, on_or_before: date) -> dict[str, float]:
++    """Latest series value on/before a day per company (used for window deltas)."""
++    if not ids:
++        return {}
++    rows = await fetch_all(conn, "select distinct on (company_id) company_id, value from metric_series where metric = :m and "
++                                 "company_id = any(cast(:ids as text[])) and day <= :d order by company_id, day desc", m=metric, ids=ids, d=on_or_before)
++    return {r["company_id"]: float(r["value"]) for r in rows}
++
++
++async def settings_value(conn: AsyncConnection, key: str) -> Any:
++    return await fetch_val(conn, "select value from settings_kv where key = :k", k=key)
++
++
++__all__ = ["COMPANY_SORTS", "COUNT_CAP", "EVENT_SORTS", "MAX_LIMIT", "WINDOWS", "bounded_count", "clamp", "company_filters", "company_page_ids",
++           "count_events", "csv_list", "days_ago", "event_filters", "fetch_cards_by_ids", "fetch_event", "fetch_events", "get_company",
++           "metric_series", "metric_values_at", "now_utc", "parse_bool", "parse_iso", "require_company", "settings_value", "window_start"]

added src/companyatlas/api/ratelimit.py +173 −0

++"""In-process token-bucket rate limiting (spec §136: tiers anonymous / authenticated / paid / internal).
++
++Key = client IP (first hop of `X-Forwarded-For`) for anonymous traffic, or the API key id when a valid `X-CA-API-Key` is presented.
++API keys are looked up by sha256 hash in `api_keys` (60 s in-process cache, negative results too); `last_used_at`/`request_count`
++are flushed lazily every `FLUSH_EVERY_S`. Admin requests (valid `X-CA-Admin-Token`) and health/docs paths bypass the limiter.
++`429` carries `Retry-After`; every limited response carries `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Tier`.
++"""
++from __future__ import annotations
++
++import asyncio
++import hashlib
++import logging
++import time
++from dataclasses import dataclass, field
++from datetime import UTC, datetime
++from typing import Any
++
++from fastapi import Request
++
++from companyatlas.api.common import AtlasJSONResponse, TTLCache, client_ip, is_admin_request
++from companyatlas.db import connection, execute, fetch_one, transaction
++
++log = logging.getLogger("companyatlas.api.ratelimit")
++
++TIER_LIMITS_PER_MIN: dict[str, int | None] = {"anonymous": 120, "authenticated": 600, "paid": 3000, "internal": None}
++KEY_CACHE_TTL_S = 60.0
++FLUSH_EVERY_S = 30.0
++BYPASS_PREFIXES = ("/health", "/ready", "/api/v1/health", "/api/v1/docs", "/api/v1/openapi.json")
++MAX_BUCKETS = 50_000
++
++
++@dataclass(slots=True)
++class Bucket:
++    tokens: float
++    updated: float
++
++
++@dataclass
++class RateLimiter:
++    limits: dict[str, int | None] = field(default_factory=lambda: dict(TIER_LIMITS_PER_MIN))
++    buckets: dict[str, Bucket] = field(default_factory=dict)
++
++    def take(self, key: str, tier: str, now: float | None = None) -> tuple[bool, int, int, float]:
++        """Consume one token. Returns (allowed, limit, remaining, retry_after_s)."""
++        limit = self.limits.get(tier, self.limits["anonymous"])
++        if limit is None:
++            return True, 0, 0, 0.0
++        now = time.monotonic() if now is None else now
++        rate = limit / 60.0
++        b = self.buckets.get(key)
++        if b is None:
++            if len(self.buckets) >= MAX_BUCKETS:
++                self._evict(now)
++            b = self.buckets[key] = Bucket(tokens=float(limit), updated=now)
++        else:
++            b.tokens = min(float(limit), b.tokens + (now - b.updated) * rate)
++            b.updated = now
++        if b.tokens >= 1.0:
++            b.tokens -= 1.0
++            return True, limit, int(b.tokens), 0.0
++        retry = (1.0 - b.tokens) / rate
++        return False, limit, 0, retry
++
++    def _evict(self, now: float) -> None:
++        stale = [k for k, b in self.buckets.items() if now - b.updated > 120]
++        for k in stale:
++            self.buckets.pop(k, None)
++        if len(self.buckets) >= MAX_BUCKETS:      # still full: drop the oldest half
++            for k in sorted(self.buckets, key=lambda k: self.buckets[k].updated)[: MAX_BUCKETS // 2]:
++                self.buckets.pop(k, None)
++
++
++limiter = RateLimiter()
++_key_cache = TTLCache(max_items=10_000)
++_usage: dict[str, int] = {}
++_usage_lock = asyncio.Lock()
++_last_flush = time.monotonic()
++
++
++def hash_key(raw: str) -> str:
++    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
++
++
++async def resolve_api_key(raw: str | None) -> dict[str, Any] | None:
++    """`{id, tier, name}` for a valid, non-revoked key; None otherwise (cached 60 s either way)."""
++    if not raw or len(raw) < 16 or len(raw) > 200:
++        return None
++    h = hash_key(raw)
++    hit = _key_cache.get(h)
++    if hit is not None:
++        return hit or None
++    try:
++        async with connection() as conn:
++            row = await fetch_one(conn, "select id, tier, name from api_keys where key_hash = :h and revoked_at is null", h=h)
++    except Exception:
++        log.warning("api key lookup failed", exc_info=True)
++        return None
++    info = {"id": row["id"], "tier": row["tier"], "name": row["name"]} if row else {}
++    _key_cache.set(h, info, KEY_CACHE_TTL_S)
++    return info or None
++
++
++async def _write_usage(batch: dict[str, int]) -> None:
++    if not batch:
++        return
++    try:
++        async with transaction() as conn:
++            for kid, n in batch.items():
++                await execute(conn, "update api_keys set last_used_at = :t, request_count = request_count + :n where id = :id",
++                              t=datetime.now(UTC), n=n, id=kid)
++    except Exception:
++        log.warning("api key usage flush failed", exc_info=True)
++
++
++async def _note_usage(key_id: str) -> None:
++    global _last_flush
++    async with _usage_lock:
++        _usage[key_id] = _usage.get(key_id, 0) + 1
++        if time.monotonic() - _last_flush < FLUSH_EVERY_S:
++            return
++        batch, _last_flush = dict(_usage), time.monotonic()
++        _usage.clear()
++    await _write_usage(batch)
++
++
++async def flush_usage() -> None:
++    """Force a usage flush (tests / shutdown)."""
++    global _last_flush
++    async with _usage_lock:
++        batch, _last_flush = dict(_usage), time.monotonic()
++        _usage.clear()
++    await _write_usage(batch)
++
++
++def _is_local_server_side(request: Request) -> bool:
++    if request.headers.get("x-forwarded-for") or request.headers.get("x-real-ip"):
++        return False
++    host = request.client.host if request.client else ""
++    return host in ("127.0.0.1", "::1")
++
++
++async def rate_limit_middleware(request: Request, call_next):  # type: ignore[no-untyped-def]
++    path = request.url.path
++    if request.method == "OPTIONS" or path.startswith(BYPASS_PREFIXES):
++        return await call_next(request)
++    if is_admin_request(request):
++        response = await call_next(request)
++        response.headers["x-ratelimit-tier"] = "admin"
++        return response
++    key_info = await resolve_api_key(request.headers.get("x-ca-api-key"))
++    if key_info:
++        tier, bucket_key = key_info["tier"], f"key:{key_info['id']}"
++        asyncio.get_running_loop().create_task(_note_usage(key_info["id"]))
++    elif _is_local_server_side(request):
++        # Next.js server components fetch the loopback API without X-Forwarded-For: that is our own SSR, not a public client.
++        # Browser traffic proxied through the Next rewrite (and through Caddy) always carries X-Forwarded-For and stays anonymous.
++        tier, bucket_key = "internal", "internal:ssr"
++    else:
++        tier, bucket_key = "anonymous", f"ip:{client_ip(request)}"
++    allowed, limit, remaining, retry = limiter.take(bucket_key, tier)
++    if not allowed:
++        return AtlasJSONResponse({"detail": "rate limit exceeded"}, status_code=429,
++                                 headers={"retry-after": str(max(1, int(retry + 0.999))), "x-ratelimit-limit": str(limit),
++                                          "x-ratelimit-remaining": "0", "x-ratelimit-tier": tier, "cache-control": "no-store"})
++    response = await call_next(request)
++    response.headers["x-ratelimit-tier"] = tier
++    if limit:
++        response.headers["x-ratelimit-limit"] = str(limit)
++        response.headers["x-ratelimit-remaining"] = str(remaining)
++    return response
++
++
++__all__ = ["TIER_LIMITS_PER_MIN", "RateLimiter", "flush_usage", "hash_key", "limiter", "rate_limit_middleware", "resolve_api_key"]

added src/companyatlas/api/routers/admin.py +561 −0

Large diff (561 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/api/routers/companies.py +354 −0

Large diff (354 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/api/routers/countries.py +54 −0

Large diff (54 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/api/routers/events.py +104 −0

Large diff (104 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/api/routers/exports.py +183 −0

Large diff (183 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/api/routers/industries.py +60 −0

Large diff (60 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/api/routers/live.py +37 −0

Large diff (37 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/api/routers/owner.py +163 −0

Large diff (163 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/api/routers/provenance.py +201 −0

Large diff (201 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/api/routers/rankings.py +29 −0

Large diff (29 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/api/routers/search.py +254 −0

Large diff (254 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/api/routers/signals.py +66 −0

Large diff (66 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/api/routers/sitemap.py +48 −0

Large diff (48 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/api/routers/stats.py +116 −0

Large diff (116 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/api/serializers.py +290 −0

Large diff (290 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/api/sse.py +85 −0

Large diff (85 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/commands/api_keys.py +75 −0

Large diff (75 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/commands/intel.py +252 −0

Large diff (252 lines) is not loaded by default to keep the page fast.Load diff

modified src/companyatlas/config.py +16 −0

Large diff (28 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/services/alerts.py +237 −0

Large diff (237 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/services/clustering.py +113 −0

Large diff (113 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/services/digest.py +76 −0

Large diff (76 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/services/events.py +904 −0

Large diff (904 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/services/llm/__init__.py +1 −0

Large diff (1 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/services/llm/ask.py +275 −0

Large diff (275 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/services/llm/enrich.py +357 −0

Large diff (357 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/services/llm/gateway.py +301 −0

Large diff (301 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/services/llm/prompts.py +58 −0

Large diff (58 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/services/llm/schemas.py +155 −0

Large diff (155 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/services/metrics.py +591 −0

Large diff (591 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/services/retention.py +91 −0

Large diff (91 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/services/signals.py +273 −0

Large diff (273 lines) is not loaded by default to keep the page fast.Load diff

added src/companyatlas/services/trends.py +136 −0

Large diff (136 lines) is not loaded by default to keep the page fast.Load diff

modified src/companyatlas/taxonomy.py +25 −2

Large diff (39 lines) is not loaded by default to keep the page fast.Load diff

added tests/factories.py +168 −0

Large diff (168 lines) is not loaded by default to keep the page fast.Load diff

added tests/test_api_admin.py +139 −0

Large diff (139 lines) is not loaded by default to keep the page fast.Load diff

added tests/test_api_companies.py +156 −0

Large diff (156 lines) is not loaded by default to keep the page fast.Load diff

added tests/test_api_limits_exports.py +102 −0

Large diff (102 lines) is not loaded by default to keep the page fast.Load diff

added tests/test_api_owner.py +58 −0

Large diff (58 lines) is not loaded by default to keep the page fast.Load diff

added tests/test_api_provenance.py +72 −0

Large diff (72 lines) is not loaded by default to keep the page fast.Load diff

added tests/test_api_public.py +198 −0

Large diff (198 lines) is not loaded by default to keep the page fast.Load diff

added tests/test_api_support.py +220 −0

Large diff (220 lines) is not loaded by default to keep the page fast.Load diff

added tests/test_ask_parser.py +73 −0

Large diff (73 lines) is not loaded by default to keep the page fast.Load diff

added tests/test_events_rules.py +332 −0

Large diff (332 lines) is not loaded by default to keep the page fast.Load diff

added tests/test_llm_gateway.py +159 −0

Large diff (159 lines) is not loaded by default to keep the page fast.Load diff

added tests/test_metrics.py +184 −0

Large diff (184 lines) is not loaded by default to keep the page fast.Load diff

added tests/test_signals.py +107 −0

Large diff (108 lines) is not loaded by default to keep the page fast.Load diff

spb/company-atlas

intelligence layer (events, clustering, LLM gateway + prompts, metrics, signals, trends, alerts, retention) and API v1 (74 endpoints, SSE, rate limits, exports, admin)

Theme