@startsimpli/integrations 0.1.3 → 0.1.5

package/src/corpus/types.ts

@@ -0,0 +1,354 @@
+/**
+ * The corpus contract — the typed layer between the tenant data API and the two
+ * product surfaces (bd startsim-768w.38.6 Library, startsim-768w.38.7 Ask).
+ *
+ * WHY A CONTRACT AND NOT A CLIENT: the composers take an INJECTED api the same
+ * way `ConnectionsPage` does, so they depend on a SHAPE. A test hands them an
+ * object literal; an app hands them an adapter over its own HTTP client. No
+ * React context, no app-local provider.
+ *
+ * WHY EVERY NOUN HERE IS SOURCE-AGNOSTIC (bd startsim-768w.38.2, and the rule
+ * ratified in feedback_foundry_builder_generic_not_usecase): the record a
+ * Granola meeting becomes must be the SAME record a Dropbox file becomes. There
+ * is no `GranolaNote`, no `transcript` field, and no `if (source === ...)`
+ * anywhere in this package. A vendor difference arrives as DATA — a source key,
+ * a source label, a named section — exactly the way the connector catalog
+ * already works.
+ *
+ * THE TEST APPLIED TO EVERY FIELD BELOW: would this still make sense if the only
+ * connected source were Dropbox? `sections` passes (a PDF has extracted text the
+ * way a meeting has a transcript). A `speakers` field would not have, which is
+ * why speakers are `participants` and why they are `PartyRef`s.
+ *
+ * SCHEMA COUPLING IS DELIBERATELY CONFINED: nothing outside `./entities` knows
+ * how a `SourceDocument` is stored. When bd startsim-768w.38.2 lands and the
+ * attribute names shift, `./entities.ts` is the one file that changes.
+ */
+
+/**
+ * Which connector filled a record. FREE-FORM on purpose — `granola`, `dropbox`,
+ * `gdrive`, `stripe`, `upload`, and whatever ships next week. A union type here
+ * would mean a fourth source could not be added without an app change, which is
+ * precisely the thing the epic forbids.
+ */
+export type SourceKey = string;
+
+/**
+ * The tenant boundary as the data plane actually enforces it.
+ *
+ * `orgId` is the JWT `org_id` claim — under customer workspaces (bd
+ * startsim-768w.34.4) that is the CUSTOMER's org, not the foundry's root
+ * company, and it is the line an answer must never cross.
+ *
+ * `ownerSub` is the central user_id stamped on every row as `owner_sub`. Today
+ * the tenant API scopes reads by org and by readable TYPE, not by owner — so a
+ * scope carrying only `orgId` is the honest default. A caller that wants the
+ * narrower posture passes `ownerSub` and gets it enforced here as well.
+ */
+export interface CorpusScope {
+  orgId: string;
+  ownerSub?: string;
+}
+
+/**
+ * A person or company the corpus refers to, as referenced FROM a record.
+ * One noun with a subtype, never separate Contact/Customer types
+ * (feedback_brutally_generic).
+ */
+export interface PartyRef {
+  id: string;
+  name: string;
+  /** `person` | `company` | anything a tenant models. Data, not an enum. */
+  kind?: string;
+  email?: string;
+}
+
+/** A Party as a first-class record. */
+export interface Party extends PartyRef {
+  source: SourceKey;
+  sourceLabel?: string;
+  sourceRef?: string;
+  emails?: string[];
+  scope: CorpusScope;
+}
+
+/**
+ * Long-form text a source carried alongside the document's own body.
+ *
+ * A Granola note contributes `{key:'transcript', label:'Transcript'}`; a Dropbox
+ * PDF contributes `{key:'extracted_text', label:'Extracted text'}`; a Stripe
+ * invoice contributes none. The composer renders whatever it is handed and names
+ * it with the source's own label, so no screen knows what a transcript is.
+ */
+export interface DocumentSection {
+  key: string;
+  label: string;
+  text: string;
+}
+
+/**
+ * The corpus unit. Everything an AI reads is one of these, whatever pulled it in.
+ */
+export interface SourceDocument {
+  id: string;
+  title: string;
+  /** The primary readable text — a summary, a description, a body. */
+  body: string;
+  /** Additional long-form the source provided. See `DocumentSection`. */
+  sections: DocumentSection[];
+  /** When the thing HAPPENED, which is not when it was ingested. */
+  occurredAt: string | null;
+  source: SourceKey;
+  /** Human name of the source, from the catalog — never hardcoded per vendor. */
+  sourceLabel: string;
+  /** The vendor's own id, so a row can be traced back out of the system. */
+  sourceRef: string;
+  /** Deep link into the vendor, when it has one. */
+  url?: string;
+  participants: PartyRef[];
+  scope: CorpusScope;
+  /** When the connector last wrote this row. Drives the freshness claim. */
+  ingestedAt?: string | null;
+}
+
+/**
+ * Stripe's side of the corpus, as ONE type discriminated by subtype
+ * (`charge` | `invoice` | `subscription` | ...), pointing at a Party.
+ * A future billing connector fills the same type.
+ */
+export interface MoneyEvent {
+  id: string;
+  subtype: string;
+  /** Minor units, as every payment vendor reports them. */
+  amount: number;
+  currency: string;
+  status: string;
+  occurredAt: string | null;
+  source: SourceKey;
+  sourceLabel: string;
+  sourceRef: string;
+  url?: string;
+  description?: string;
+  party: PartyRef | null;
+  scope: CorpusScope;
+}
+
+/**
+ * Freshness is part of the SCREEN, not a settings page (bd startsim-768w.38.6).
+ * A corpus silently four days stale is what makes an AI answer confidently
+ * wrong, so the Library states it per source and the Ask surface repeats it.
+ */
+export interface SourceFreshness {
+  source: SourceKey;
+  label: string;
+  /** How many documents this source has contributed to the corpus. */
+  documentCount: number;
+  lastSyncedAt: string | null;
+  /**
+   * `ok` — synced recently and cleanly.
+   * `stale` — the last sync succeeded but was long enough ago to matter.
+   * `error` — the last sync failed; the corpus is missing whatever came after.
+   * `never` — connected but has never delivered a record.
+   */
+  status: 'ok' | 'stale' | 'error' | 'never';
+  /** Why it is not `ok`, in the words the server used. */
+  detail?: string;
+}
+
+/** DRF PageNumberPagination, which is what the tenant data API speaks. */
+export interface CorpusPage<T> {
+  count: number;
+  next: string | null;
+  previous: string | null;
+  results: T[];
+  /**
+   * Which of the requested filters the SERVER actually applied.
+   *
+   * A search box wired to a backend that ignores `search` renders an unfiltered
+   * list that looks filtered, which is a lie the user has no way to catch. When
+   * this is present, the Library states the gap on the screen instead. Omit it
+   * and the composer assumes everything requested was honoured.
+   */
+  appliedFilters?: string[];
+}
+
+/**
+ * Every filter here is a SERVER parameter (CLAUDE.md rule 8). The Library never
+ * loads the corpus and filters it in the browser — that breaks the count, breaks
+ * the page, and stops working at exactly the size where it starts to matter.
+ */
+export interface DocumentQuery {
+  search?: string;
+  source?: SourceKey;
+  partyId?: string;
+  /** ISO instants, filtering on `occurredAt`. */
+  occurredAfter?: string;
+  occurredBefore?: string;
+  page?: number;
+  pageSize?: number;
+}
+
+/**
+ * What the composers are handed. An app implements it over its own HTTP client;
+ * `createCorpusApi` in `./client` does that for the tenant `/api/v1/*` endpoints.
+ */
+export interface CorpusApi {
+  listDocuments(query: DocumentQuery): Promise<CorpusPage<SourceDocument>>;
+  getDocument(id: string): Promise<SourceDocument>;
+  listParties(query?: { search?: string; page?: number; pageSize?: number }): Promise<CorpusPage<Party>>;
+  /** Per-source freshness, for the strip at the top of the Library. */
+  listSources(): Promise<SourceFreshness[]>;
+  /**
+   * Optional because a tenant with no payment connector has no money events, and
+   * a corpus surface that requires one would fail the Dropbox-only test.
+   */
+  listMoneyEvents?(query?: {
+    partyId?: string;
+    search?: string;
+    page?: number;
+    pageSize?: number;
+  }): Promise<CorpusPage<MoneyEvent>>;
+}
+
+// ---------------------------------------------------------------------------
+//  Ask & Generate (bd startsim-768w.38.7)
+// ---------------------------------------------------------------------------
+
+/**
+ * ASK answers a question from the corpus. GENERATE produces a draft — a
+ * contract, a follow-up, a summary — from a prompt plus the corpus. Same
+ * retrieval, same citation rules, one surface; the only difference is what the
+ * model is told to emit.
+ */
+export type AskMode = 'ask' | 'generate';
+
+/** A record the retriever selected, with the reason it selected it. */
+export interface RetrievedDocument {
+  document: SourceDocument;
+  score: number;
+  /** Which query terms hit, so the ranking can be argued with rather than trusted. */
+  matchedTerms: string[];
+  /** The passage the term matched in, for the citation card. */
+  snippet: string;
+}
+
+/**
+ * A citation the model emitted, AFTER it has been resolved back to a record the
+ * retriever actually supplied. A citation that cannot be resolved is dropped —
+ * see `AskResult.unresolvedCitations`.
+ */
+export interface Citation {
+  documentId: string;
+  document: SourceDocument;
+  /** The model's own quote, for the user to check against the record. */
+  quote: string;
+}
+
+export interface AskRequest {
+  question: string;
+  mode: AskMode;
+  scope: CorpusScope;
+  /** Extra instructions for GENERATE — tone, format, the kind of document. */
+  instructions?: string;
+  /** Narrow the corpus before retrieval, exactly like the Library's filters. */
+  filters?: Pick<DocumentQuery, 'source' | 'partyId' | 'occurredAfter' | 'occurredBefore'>;
+}
+
+/**
+ * `answered` — an answer with at least one resolved citation.
+ * `uncited` — the model produced text but nothing traceable. The UI must SAY so
+ *   rather than render it: an answer you cannot trace is an answer you cannot
+ *   trust with a contract.
+ * `no_evidence` — retrieval found nothing in scope. This is the correct outcome
+ *   of a cross-scope question and is not an error.
+ */
+export type AskStatus = 'answered' | 'uncited' | 'no_evidence';
+
+export interface AskResult {
+  status: AskStatus;
+  answer: string;
+  citations: Citation[];
+  /** Everything retrieval offered the model, so "why did it not use X" is answerable. */
+  considered: RetrievedDocument[];
+  /**
+   * Ids the model cited that retrieval never supplied. Non-empty means the model
+   * invented a source; it is surfaced, never silently swallowed.
+   */
+  unresolvedCitations: string[];
+  /**
+   * How many candidate records were discarded by the scope guard before the
+   * prompt was built. A non-zero value on a correctly-scoped API means the API
+   * returned something it should not have, and is worth seeing.
+   */
+  droppedOutOfScope: number;
+  /** Which provider/model actually answered, and whether it was a real one. */
+  provider: LlmDescription;
+  /** Freshness at answer time — an answer over a stale corpus says so. */
+  freshness?: SourceFreshness[];
+}
+
+export interface LlmDescription {
+  provider: string;
+  model: string;
+  /** False when the answer came from a stub/fixture rather than a live model. */
+  live: boolean;
+}
+
+/**
+ * The document payload handed to the model, with the id it must echo back.
+ * ONE call carries all of them (feedback_batch_llm_calls) — never a loop of N.
+ */
+export interface PromptDocument {
+  id: string;
+  title: string;
+  source: string;
+  occurredAt: string | null;
+  participants: string[];
+  text: string;
+}
+
+export interface AnswerRequest {
+  question: string;
+  mode: AskMode;
+  instructions?: string;
+  documents: PromptDocument[];
+}
+
+/** The structured shape the model must return. Validated before it is trusted. */
+export interface AnswerDraft {
+  answer: string;
+  citations: Array<{ documentId: string; quote?: string }>;
+  /** The model's own admission that the documents do not answer the question. */
+  unanswerable?: boolean;
+}
+
+/**
+ * The LLM seam. Deliberately ONE method that takes N documents, so the batching
+ * rule is structural rather than a thing a caller has to remember.
+ *
+ * `@startsimpli/llm` is the only implementation that talks to a provider — see
+ * `./llm`. Nothing in this package constructs a provider client.
+ */
+export interface CorpusLlm {
+  answer(input: AnswerRequest): Promise<AnswerDraft>;
+  describe(): LlmDescription;
+}
+
+/**
+ * What `AskPage` is injected with. An app points it at its own route handler;
+ * the handler calls `askCorpus` server-side, where the API key lives.
+ */
+export interface CorpusAskApi {
+  ask(request: AskRequest): Promise<AskResult>;
+  /**
+   * Persist a generated draft back INTO the corpus, so the draft is part of the
+   * corpus next time. Optional: a read-only deployment simply omits it and the
+   * Save control does not render.
+   */
+  saveDraft?(input: {
+    title: string;
+    body: string;
+    citations: string[];
+    scope: CorpusScope;
+  }): Promise<SourceDocument>;
+}

package/src/index.ts

@@ -12,3 +12,12 @@ export * from './types/index';
 export * from './api/index';
 export * from './hooks/index';
 export * from './components/index';
+
+/**
+ * The corpus layer — the READ side of connections (bd startsim-768w.38.6 and
+ * startsim-768w.38.7). Browser-safe by construction: the only module that talks
+ * to an LLM provider is `@startsimpli/integrations/corpus-llm`, which is NOT
+ * re-exported here, so mounting a composer can never pull a provider key into a
+ * client bundle.
+ */
+export * from './corpus/index';