@qaecy/cue-sdk 0.0.40 → 0.0.44

package/index.d.ts

@@ -41,9 +41,13 @@ export type { ProjectTable } from './lib/tables';
 export { CueExtraction } from './lib/extraction';
 export type { ExtractionRequest, ExtractionResponse } from './lib/extraction';
 export { CueLlmTools } from './lib/llm-tools';
-export type { GenerateWranglingSchemaRequest, GenerateWranglingSchemaResponse } from './lib/llm-tools';
+export type { GenerateWranglingSchemaRequest, GenerateWranglingSchemaResponse, ExistingCategoryForSuggestion, SuggestEntityCategoryRequest, SuggestEntityCategoryResponse, SuggestEntityCategoryMatch, SuggestEntityCategorySuggestion, ColumnToSuggest, ColumnCategorySuggestionResult, SuggestEntityCategoryBatchRequest, SuggestEntityCategoryBatchResponse, } from './lib/llm-tools';
 export { CueDataSources } from './lib/data-sources';
 export type { DataSourceRecord, XToRdfConfig, RmlXToRdfConfig, GraphXToRdfConfig, TypeMappingConfiguration, UploadDataSourceMode, UploadDataSourceResult, } from './lib/data-sources';
+export { CueGisSources } from './lib/gis-sources';
+export type { GisSourceRecord, GisSourceUploadFormat, GisSourceCrs } from './lib/gis-sources';
+export { CueSemanticTemplate } from './lib/semantic-template';
+export type { MutationResult as SemanticTemplateMutationResult, BatchMutationResult as SemanticTemplateBatchMutationResult, ContentCategoryInput, EntityCategoryInput, EntityRelationshipInput, } from './lib/semantic-template';
 export { CueContexts } from './lib/contexts';
 export type { ContextDoc, ContextItem, McpContext } from './lib/models';
 export { CueAppData } from './lib/app-data';

package/index.js

@@ -1,40 +1,42 @@
-import { B as a, C as u, a as C, b as t, c as r, d as i, e as o, f as c, g as n, h as p, i as S, j as E, k as A, l as m, m as P, n as R, o as g, p as l, q as D, r as j, s as U, t as x, u as d, v as f, w as h, x as I, y, z as T, A as _, D as b, E as q, F as v, G as w, R as B, S as F, H as G, I as L } from "./document-filter-Ccb84D3H.js";
+import { B as a, C as u, a as C, b as t, c as i, d as r, e as o, f as c, g as n, h as p, i as S, j as m, k as E, l as A, m as P, n as R, o as l, p as g, q as D, r as j, s as U, t as x, u as d, v as f, w as h, x as I, y as T, z as y, A as G, D as _, E as b, F as q, G as v, H as w, I as B, R as F, S as L, J as N, K as O } from "./document-filter-Cj0Yql1C.js";
 export {
   a as BASE_CURRENCY,
   u as Cue,
   C as CueAdmin,
   t as CueApi,
-  r as CueAppData,
-  i as CueApps,
+  i as CueAppData,
+  r as CueApps,
   o as CueAuth,
   c as CueCache,
   n as CueContexts,
   p as CueCurrency,
   S as CueDataSources,
-  E as CueDmsApi,
-  A as CueDocumentFilter,
-  m as CueExtraction,
+  m as CueDmsApi,
+  E as CueDocumentFilter,
+  A as CueExtraction,
   P as CueGis,
-  R as CueIndexApi,
+  R as CueGisSources,
+  l as CueIndexApi,
   g as CueLlmTools,
-  l as CueMcp,
-  D as CuePrivileges,
-  j as CueProcessingApi,
-  U as CueProfile,
-  x as CueProjectDocuments,
-  d as CueProjectEntities,
-  f as CueProjectSchema,
-  h as CueProjectView,
-  I as CueProjects,
+  D as CueMcp,
+  j as CuePrivileges,
+  U as CueProcessingApi,
+  x as CueProfile,
+  d as CueProjectDocuments,
+  f as CueProjectEntities,
+  h as CueProjectSchema,
+  I as CueProjectView,
+  T as CueProjects,
   y as CueRequestError,
-  T as CueSignUp,
-  _ as CueSignal,
-  b as CueStorage,
-  q as CueSyncApi,
-  v as CueTables,
-  w as CueUserSettings,
-  B as REQUIRED_ROLES,
-  F as SUPPORTED_CURRENCIES,
-  G as configureScanWasm,
-  L as cueComputed
+  G as CueSemanticTemplate,
+  _ as CueSignUp,
+  b as CueSignal,
+  q as CueStorage,
+  v as CueSyncApi,
+  w as CueTables,
+  B as CueUserSettings,
+  F as REQUIRED_ROLES,
+  L as SUPPORTED_CURRENCIES,
+  N as configureScanWasm,
+  O as cueComputed
 };

package/lib/api.d.ts

@@ -1,3 +1,4 @@
+import { CueBlobStorage } from 'js-databases';
 import { CueAuth } from './auth';
 import { SearchRequest, SearchResponse, ShaclValidationReport, UnitsConsumedDto } from './models';
 import { CueProjects } from './project';
@@ -14,6 +15,8 @@ import { CueProcessingApi } from './processing';
 import { CueDmsApi } from './dms';
 import { CueLlmTools } from './llm-tools';
 import { CueDataSources } from './data-sources';
+import { CueGisSources } from './gis-sources';
+import { CueSemanticTemplate } from './semantic-template';
 export declare class CueApi {
     private readonly _auth;
     private readonly _gatewayUrl;
@@ -42,11 +45,17 @@ export declare class CueApi {
     readonly llmTools: CueLlmTools;
     /** Project-scoped data sources — reusable raw-data-to-RDF pipelines writing into their own named graph. */
     readonly dataSources: CueDataSources;
+    /** Project-scoped GIS sources — user-uploaded GeoJSON/KML/Shapefile feature sets, returned by
+     *  `cue.gis` under the 'custom' category alongside every other GIS category. */
+    readonly gisSources: CueGisSources;
+    /** Mutates a project's custom extraction/classification schema (content categories, entity
+     *  categories, entity relationships) and reloads its `databases-cue` schema graph. */
+    readonly semanticTemplate: CueSemanticTemplate;
     /** Active language used for language-sensitive SPARQL queries across all project classes. */
     language: string;
     /** Updates the active language. All project classes (`CueProjectSchema`, `CueProjectDocuments`, `CueProjectEntities`) read this at query time. */
     setLanguage(lang: string): void;
-    constructor(_auth: CueAuth, _gatewayUrl: string, projects: CueProjects, sync?: CueSyncApi | undefined);
+    constructor(_auth: CueAuth, _gatewayUrl: string, projects: CueProjects, sync?: CueSyncApi | undefined, blob?: CueBlobStorage);
     /**
      * Returns standard authentication headers for the current user.
      * Useful when calling Cue-backed services directly (e.g. the GIS proxy).
@@ -60,8 +69,14 @@ export declare class CueApi {
     /**
      * Execute a SPARQL query against the project's triplestore.
      * The user must be authenticated before calling this.
+     *
+     * The gateway resolves which graph backend (qlever, cue, …) actually serves
+     * the query per-project — `graphType` here only needs to distinguish legacy
+     * Fuseki, which lives on its own static Kong route rather than that
+     * per-project routing. Pass it explicitly if the caller already knows;
+     * otherwise it's looked up from the project's own settings.
      */
-    sparql(query: string, projectId: string, graphType?: string): Promise<unknown>;
+    sparql(query: string, projectId: string, graphType?: 'fuseki' | 'qlever'): Promise<unknown>;
     /**
      * Validate a SHACL shape against the project's triplestore.
      *
@@ -75,7 +90,7 @@ export declare class CueApi {
     shacl(shape: string, projectId: string, options?: {
         format?: 'json-ld' | 'turtle';
         verbose?: boolean;
-        graphType?: string;
+        graphType?: 'fuseki' | 'qlever';
     }): Promise<ShaclValidationReport | string>;
     /**
      * Per-extension credit rates for `tier` (e.g. `{ pdf: 4, ifc: 2, dwg: 2 }`),

package/lib/cue.d.ts

@@ -111,7 +111,7 @@ export declare class Cue {
      */
     createProjectEntities(projectId: string, opts?: {
         rdfBase?: string;
-        graphType?: string;
+        graphType?: 'fuseki' | 'qlever';
         verbose?: boolean;
     }): CueProjectEntities;
     /**
@@ -128,7 +128,7 @@ export declare class Cue {
     createProjectDocuments(projectId: string, opts?: {
         language?: string;
         rdfBase?: string;
-        graphType?: string;
+        graphType?: 'fuseki' | 'qlever';
         verbose?: boolean;
     }): CueProjectDocuments;
 }

package/lib/data-sources.d.ts

@@ -1,5 +1,6 @@
+import { CueBlobStorage } from 'js-databases';
 import { CueAuth } from './auth';
-export type XToRdfConfig = RmlXToRdfConfig | GraphXToRdfConfig | DecompositionConfig;
+export type XToRdfConfig = RmlXToRdfConfig | GraphXToRdfConfig | DecompositionConfig | SheetXToRdfConfig;
 interface XToRdfConfigBase {
     /** Steps run on the transform's output, in order — see `XToRdfPostProcessingStep`. */
     postProcessing?: XToRdfPostProcessingStep[];
@@ -51,6 +52,47 @@ export interface DecompositionConfig extends XToRdfConfigBase {
      */
     levels: Record<string, unknown>[];
 }
+export interface SheetXToRdfConfig extends XToRdfConfigBase {
+    type: 'sheet';
+    mapping: SheetMappingConfiguration;
+}
+/**
+ * How a spreadsheet's columns become RDF: every column is either ignored, an entity — minted
+ * onto the same deterministic-IRI scheme `graph`/`decomposition` use
+ * (`<rdfBase><projectId>/<uuidv5(value+categoryIri)>`) — or an attribute of one entity column (a
+ * `qcy:Property` node linked via `qcy:hasProperty`). A relationship connects two entity columns
+ * via a chosen predicate, read off the same row. Unlike `wizardConfig`/`levels` above, this is
+ * NOT opaque to the backend — it's the actual input the sheet transform interprets row by row.
+ */
+export interface SheetMappingConfiguration {
+    id?: string;
+    name: string;
+    columnRoles: Record<string, SheetColumnRole>;
+    relationMappings: SheetRelationMapping[];
+    fileLinkage?: SheetFileLinkage | null;
+}
+export type SheetColumnRole = {
+    kind: 'unmapped';
+} | {
+    kind: 'entity';
+    categoryIri: string;
+} | {
+    kind: 'attribute';
+    entityColumn: string;
+    label: string;
+};
+export interface SheetRelationMapping {
+    sourceColumn: string;
+    targetColumn: string;
+    predicateIri: string;
+    /** True when the predicate points from target to source instead of source to target. */
+    reversed?: boolean;
+}
+/** "Rows represent files" — a sheet-wide special case, not a per-column role. */
+export interface SheetFileLinkage {
+    filePathColumn: string;
+    md5Column?: string;
+}
 /**
  * A step applied to a transform's *output*, after the CONSTRUCT query (or RML mapping) has run.
  *
@@ -139,14 +181,25 @@ export interface DataSourceProgressEvent {
 export declare class CueDataSources {
     private readonly _auth;
     private readonly _gatewayUrl;
-    constructor(_auth: CueAuth, _gatewayUrl: string);
+    private readonly _blob?;
+    constructor(_auth: CueAuth, _gatewayUrl: string, _blob?: CueBlobStorage | undefined);
     createDataSource(projectId: string, name: string, config: XToRdfConfig): Promise<DataSourceRecord>;
     updateDataSource(projectId: string, id: string, updates: {
         name?: string;
         config?: XToRdfConfig;
     }): Promise<DataSourceRecord>;
-    /** Hard delete — also removes the data source's triples from the graph/ledger. */
-    deleteDataSource(projectId: string, id: string): Promise<void>;
+    /**
+     * Hard delete — also removes the data source's triples from the graph/ledger. This fetches the
+     * whole named graph and round-trips to the ledger/graph store, which can take tens of seconds;
+     * the endpoint streams NDJSON progress while that's in flight — pass `onProgress` to receive it
+     * (see `uploadData`'s doc comment for the wire format). Still bounded by a client-side timeout
+     * covering the server's own bounded retries against the ledger/graph store (30s x up to 3
+     * retries each, for both) plus normal request/response overhead, in case the stream stalls
+     * with no further progress.
+     */
+    deleteDataSource(projectId: string, id: string, onProgress?: (event: DataSourceProgressEvent) => void): Promise<{
+        removed: number;
+    }>;
     /**
      * Uploads new data to be transformed by the data source's stored config and
      * committed into its named graph. `mode: 'replace'` swaps out everything
@@ -156,11 +209,13 @@ export declare class CueDataSources {
      * they're all loaded into one shared graph server-side before the stored
      * CONSTRUCT query runs against it. `type: 'rml'` configs expect exactly one.
      *
-     * The endpoint streams NDJSON progress while the upload is in flight — pass
-     * `onProgress` to receive it. The call still resolves/rejects only once, with
-     * the final result or an `Error` built from the stream's `error` line (a
-     * non-2xx HTTP status, e.g. an auth/guard rejection before the handler even
-     * runs, is still thrown from `response.ok` as before).
+     * Each file is uploaded straight to storage first (see `_stageFiles`) — the request that
+     * follows carries only small file references, never the bytes, so file size never runs into
+     * Cloud Run's request-size limit. `onProgress` receives `phase: 'uploading'` events for that
+     * step, then the endpoint's usual NDJSON processing-progress events once the notify request is
+     * in flight. The call still resolves/rejects only once, with the final result or an `Error`
+     * built from the stream's `error` line (a non-2xx HTTP status, e.g. an auth/guard rejection
+     * before the handler even runs, is still thrown from `response.ok` as before).
      */
     uploadData(projectId: string, id: string, files: Blob[], mode: UploadDataSourceMode, onProgress?: (event: DataSourceProgressEvent) => void): Promise<UploadDataSourceResult>;
     /**
@@ -168,12 +223,23 @@ export declare class CueDataSources {
      * without creating a data source or writing anything to the graph/ledger —
      * for previewing a transform (e.g. while building a CONSTRUCT query or RML
      * mapping) before saving it. Same transform code as `uploadData`, so a
-     * preview never drifts from what an actual upload would produce. Streams
-     * progress the same way — see `uploadData`'s doc comment.
+     * preview never drifts from what an actual upload would produce. Uploads
+     * `files` to storage first and streams progress the same way — see
+     * `uploadData`'s doc comment.
      */
     previewTransform(projectId: string, config: XToRdfConfig, files: Blob[], onProgress?: (event: DataSourceProgressEvent) => void): Promise<{
         turtle: string;
     }>;
+    /**
+     * Uploads every file straight to the raw bucket's `${projectId}/_tmp-uploads/` prefix (server
+     * deletes each one right after processing it — see writers-commands' `_withTempFiles`), so
+     * `uploadData`/`previewTransform`'s own request only ever carries small JSON references —
+     * bytes never cross Cloud Run's request-size cap, no matter how large the file. Reports
+     * upload-byte progress through `onProgress` as `phase: 'uploading'`, aggregated across every
+     * file in the batch (not most-recent-file-wins) since callers pass everything to `uploadData`
+     * in one call.
+     */
+    private _stageFiles;
     /** Reads an NDJSON response (`{type:'progress',...}` lines, then one `{type:'result',...}`
      *  or `{type:'error',...}` line), forwarding progress events to `onProgress` and
      *  resolving/rejecting with the terminal event. The HTTP status alone can't signal

package/lib/document-filter.d.ts

@@ -27,7 +27,7 @@ export declare class CueDocumentFilter {
     private readonly _api;
     private readonly _projectId;
     private readonly _graphType?;
-    constructor(_api: CueApi, _projectId: string, _graphType?: string | undefined);
+    constructor(_api: CueApi, _projectId: string, _graphType?: "fuseki" | "qlever" | undefined);
     /**
      * Returns which mime, content and entity-category options are available among
      * documents that satisfy `applied`. Pass an empty object (or omit) to get

package/lib/documents.d.ts

@@ -52,7 +52,7 @@ export declare class CueProjectDocuments {
     readonly projectDocumentsData: ReadonlySignal<ProjectDocumentsData>;
     constructor(_api: CueApi, _projectId: string, language?: string, 
     /** Override the RDF resource base URL. Defaults to `https://cue.qaecy.com/r/`. */
-    rdfBase?: string, _graphType?: string | undefined, _verbose?: boolean);
+    rdfBase?: string, _graphType?: "fuseki" | "qlever" | undefined, _verbose?: boolean);
     /**
      * Resets all document state. Call when the active project changes.
      * Follow with `fetchOverview()` once the triplestore is ready.

package/lib/entities.d.ts

@@ -70,7 +70,7 @@ export declare class CueProjectEntities {
     readonly entityGraph: ReadonlySignal<ProjectEntitiesData | undefined>;
     constructor(_api: CueApi, _projectId: string, 
     /** Override the RDF resource base URL. Defaults to `https://cue.qaecy.com/r/`. */
-    rdfBase?: string, _graphType?: string | undefined, _verbose?: boolean);
+    rdfBase?: string, _graphType?: "fuseki" | "qlever" | undefined, _verbose?: boolean);
     /**
      * Constructs the full RDF IRI for the given entity UUID.
      * Use this to bridge the UUID-based batch APIs and the IRI-based per-entity APIs.

package/lib/gis-sources.d.ts

@@ -0,0 +1,57 @@
+import { FeatureCollection } from 'geojson';
+import { CueAuth } from './auth';
+export type GisSourceUploadFormat = 'geojson' | 'kml' | 'shapefile-zip';
+/** `'auto'` (the default) detects LV95/LV03 from a GeoJSON legacy `crs` member or a Shapefile's
+ *  `.prj` sidecar — pass an explicit value when a file lacks that information altogether. KML is
+ *  always WGS84 per spec and never reprojected either way. */
+export type GisSourceCrs = 'auto' | 'WGS84' | 'LV95' | 'LV03';
+export interface GisSourceRecord {
+    id: string;
+    projectId: string;
+    name: string;
+    createdAt: string;
+    createdBy: string;
+    updatedAt: string;
+    updatedBy: string;
+    /** `featureCollection.features.length`, cached at upload time. */
+    featureCount: number;
+    /** WGS84 [west, south, east, north], or null when the source has no features. */
+    bbox: [number, number, number, number] | null;
+    /** The format originally uploaded — display-only, `featureCollection` below is always WGS84. */
+    sourceFormat: GisSourceUploadFormat;
+    /** The CRS resolution that was actually applied — display-only, same reason as `sourceFormat`. */
+    sourceCrs: GisSourceCrs;
+    /** Canonical WGS84 GeoJSON — the actual feature data, same shape used everywhere else in the
+     *  GIS pipeline (see `cue.gis`). */
+    featureCollection: FeatureCollection;
+}
+/**
+ * Client for project-scoped GIS sources — user-uploaded GeoJSON/KML/Shapefile feature sets that
+ * are stored on the project and returned by `cue.gis` under the `'custom'` category, alongside
+ * every other (WFS-backed) category. Reprojection to WGS84 (from LV95/LV03) happens server-side
+ * at upload time — `featureCollection` is always WGS84.
+ *
+ * Mutations (create/update/delete) go through writers-commands and require the syncer role;
+ * reads (list/get) go through data-views.
+ *
+ * Exposed as `cue.api.gisSources`.
+ */
+export declare class CueGisSources {
+    private readonly _auth;
+    private readonly _gatewayUrl;
+    constructor(_auth: CueAuth, _gatewayUrl: string);
+    listGisSources(projectId: string): Promise<GisSourceRecord[]>;
+    getGisSource(projectId: string, id: string): Promise<GisSourceRecord>;
+    /** `filename`'s extension (`.geojson`/`.json`/`.kml`/`.zip`) tells the server which parser to
+     *  use — pass it explicitly since `file` may not carry a usable `name` (e.g. a `Blob`). */
+    createGisSource(projectId: string, name: string, file: Blob, filename: string, crs?: GisSourceCrs): Promise<GisSourceRecord>;
+    /** Omitting `file` renames the source without touching its stored features. */
+    updateGisSource(projectId: string, id: string, updates: {
+        name?: string;
+        file?: Blob;
+        filename?: string;
+        crs?: GisSourceCrs;
+    }): Promise<GisSourceRecord>;
+    deleteGisSource(projectId: string, id: string): Promise<void>;
+    private _errorMessage;
+}

package/lib/llm-tools.d.ts

@@ -1,6 +1,8 @@
 import { CueAuth } from './auth';
 export declare const ENDPOINT_WRANGLING_SCHEMA_GENERATE = "/llm-tools/wrangling-schema/generate";
 export declare const ENDPOINT_WRANGLING_SCHEMA_REFINE = "/llm-tools/wrangling-schema/refine";
+export declare const ENDPOINT_ENTITY_CATEGORY_SUGGEST = "/llm-tools/entity-category-suggestion/suggest";
+export declare const ENDPOINT_ENTITY_CATEGORY_SUGGEST_BATCH = "/llm-tools/entity-category-suggestion/suggest-batch";
 export interface GenerateWranglingSchemaRequest {
     /** Plain-language instruction for how the sheet should be reshaped. */
     prompt: string;
@@ -26,6 +28,11 @@ export interface RefineWranglingSchemaRequest {
     currentRules: Record<string, unknown>[];
     /** The new, follow-up instruction. */
     prompt: string;
+    /**
+     * How the follow-up instruction should treat `currentRules`: "append" only adds
+     * rules for what it describes, "change" revises whichever current rules it concerns.
+     */
+    mode: 'append' | 'change';
     /** Column names available in the sheet. */
     columns: string[];
     /** A handful of real rows, given as worked examples for the model. */
@@ -37,6 +44,67 @@ export interface RefineWranglingSchemaResponse {
     /** The complete, updated rule set — a replacement, not a diff. Same shape as `generate`'s. */
     rules: Record<string, unknown>[];
 }
+/** An already-existing entity category/relationship the candidate can be matched against or nested under. */
+export interface ExistingCategoryForSuggestion {
+    iri: string;
+    label: string;
+    definition?: string;
+    /** IRI of the parent category/relationship, if nested. */
+    parent?: string;
+}
+export interface SuggestEntityCategoryRequest {
+    /** The label the person typed for the new category/relationship they want to add. */
+    label: string;
+    /** Optional free-text description, if the person gave one. */
+    description?: string;
+    kind: 'category' | 'relationship';
+    /** Every already-existing entity category (or relationship, matching `kind`) in the project. */
+    existingCategories: ExistingCategoryForSuggestion[];
+    /** Project the request is scoped to. */
+    projectId: string;
+}
+export interface SuggestEntityCategoryMatch {
+    /** IRI of the existing category/relationship this candidate matches — one of the IRIs given in `existingCategories`. */
+    iri: string;
+    confidence: number;
+    reasoning: string;
+}
+export interface SuggestEntityCategorySuggestion {
+    label: string;
+    definition: string;
+    /** IRI of the existing category/relationship this new one should nest under, if any. */
+    parentIri?: string;
+    reasoning: string;
+}
+export interface SuggestEntityCategoryResponse {
+    decision: 'match' | 'new';
+    match?: SuggestEntityCategoryMatch;
+    suggestion?: SuggestEntityCategorySuggestion;
+}
+/** A sheet column not yet assigned a role, plus a few real values to seed the model. */
+export interface ColumnToSuggest {
+    column: string;
+    sampleValues?: string[];
+}
+export interface ColumnCategorySuggestionResult {
+    column: string;
+    /** "skip" — this column doesn't look like a distinct entity and is left unmapped. */
+    decision: 'skip' | 'match' | 'new';
+    match?: SuggestEntityCategoryMatch;
+    suggestion?: SuggestEntityCategorySuggestion;
+}
+export interface SuggestEntityCategoryBatchRequest {
+    /** Every currently-unmapped column, each with a few real sample values. */
+    columns: ColumnToSuggest[];
+    /** Every already-existing entity category in the project. */
+    existingCategories: ExistingCategoryForSuggestion[];
+    /** Project the request is scoped to. */
+    projectId: string;
+}
+export interface SuggestEntityCategoryBatchResponse {
+    /** One result per given column, in the same order. */
+    results: ColumnCategorySuggestionResult[];
+}
 /**
  * Client for the llm-tools guarded-LLM endpoints — small, single-purpose
  * backend calls that turn a prompt plus example data into a structured JSON
@@ -61,4 +129,19 @@ export declare class CueLlmTools {
      * than starts over.
      */
     refineWranglingSchema(request: RefineWranglingSchemaRequest): Promise<RefineWranglingSchemaResponse>;
+    /**
+     * Given a label (and optional description) for a new entity category or relationship, decides
+     * whether it already exists in the project's ontology under a different name/wording — so a
+     * person doesn't have to eyeball a long list themselves — or suggests a well-formed new one,
+     * including a parent nested under an existing category/relationship when that fits.
+     */
+    suggestEntityCategory(request: SuggestEntityCategoryRequest): Promise<SuggestEntityCategoryResponse>;
+    /**
+     * Given every currently-unmapped column in a sheet (name plus a few real values) and the
+     * project's existing entity categories, decides for each one whether it should stay unmapped,
+     * map to an existing category, or become a well-formed new one — one call covering every
+     * column at once, so the model can also stay consistent across them (e.g. not suggesting the
+     * same new category twice under different names).
+     */
+    suggestEntityCategoryBatch(request: SuggestEntityCategoryBatchRequest): Promise<SuggestEntityCategoryBatchResponse>;
 }

package/lib/models.d.ts

@@ -115,6 +115,26 @@ export interface McpContext {
     id: string;
     text: string;
 }
+/**
+ * Which service owns this project's INDEX — i.e. who applies writes to the
+ * graph/vector/FTS trio and owns the rebuild lifecycle for them.
+ *
+ * Deliberately a sibling of `graph`, not a new `graph.type` value: `cue` is not
+ * a graph backend. `databases-cue` owns all three engines, so `graph.type:
+ * 'cue'` would say "the graph lives at cue" while leaving vector and FTS
+ * pointed at `writers-index` — two owners for one project, which is the exact
+ * split this field exists to prevent. See the monorepo's
+ * `apps/databases/cue/PLAN.md` §9b.
+ */
+export type IndexService = 'writers-index' | 'cue';
+export interface IndexSettings {
+    service: IndexService;
+    /**
+     * Optional address override. Omitted means "the deployment's configured
+     * endpoint for `service`" — mirrors how `graph.uri` relates to `graph.type`.
+     */
+    uri?: string;
+}
 export interface ProjectSettings {
     views?: Array<{
         id: string;
@@ -125,8 +145,22 @@ export interface ProjectSettings {
         type: 'qlever' | 'fuseki';
         uri?: string;
     };
+    /**
+     * Absent means `writers-index` — every project predating this field is on it,
+     * so the default has to be the status quo, not the new service.
+     */
+    index?: IndexSettings;
     /** Processing tier determining credit costs. Defaults to "l" if not set. */
     tier?: 's' | 'm' | 'l';
+    /**
+     * Gzip-compress eligible raw uploads for this project (see `gzip-steps.md`
+     * Phase 3 — per-project rollout gate, not a global switch). Absent/false
+     * means uploads stay uncompressed, which must stay the default until a
+     * project has been verified end-to-end. No admin-panel UI toggles this
+     * today (same as `tier` on an existing project) — set it directly on the
+     * project's Firestore doc.
+     */
+    gzipEnabled?: boolean;
 }
 /** One daily snapshot in `QleverStats.history` — a calendar day this index's stats were (re)computed. */
 export interface QleverStatsHistoryEntry {

package/lib/project-view.d.ts

@@ -4,12 +4,14 @@ import { CueProjectEntities } from './entities';
 import { CueProjectDocuments } from './documents';
 import { ReadonlySignal } from './signal';
 import { SearchOptions, SearchResponse, CategoryDef, RelationshipDef, EntityDetailedData, EntityRelationships, ProjectEntitiesData, DocumentInfo, ProjectDocumentsData } from './models';
+import { ContentCategoryInput, EntityCategoryInput, EntityRelationshipInput } from './semantic-template';
 export interface CueProjectViewOptions {
     language: string;
     /** Override the RDF resource base URL. Defaults to `https://cue.qaecy.com/r/`. */
     rdfBase?: string;
-    /** Graph engine type from projectSettings.graph.type (e.g. 'qlever' or 'fuseki'). */
-    graphType?: string;
+    /** Graph engine type ('qlever' or legacy 'fuseki'). No longer read from the
+     * project document — see project-migration.md §4.3. */
+    graphType?: 'fuseki' | 'qlever';
     /** Enable verbose debug logging for entity and document fetch stats. */
     verbose?: boolean;
 }
@@ -60,6 +62,12 @@ export declare class CueProjectView {
     readonly searchResults: ReadonlySignal<SearchResponse | undefined>;
     private _destroyed;
     constructor(_api: CueApi, _projectId: string, { language, rdfBase, graphType, verbose }: CueProjectViewOptions);
+    /** Creates a new content category, appending it to `availableContentCategories` on success. */
+    createContentCategory(item: ContentCategoryInput): Promise<CategoryDef | null>;
+    /** Creates a new entity category, appending it to `availableEntityCategories` on success. */
+    createEntityCategory(item: EntityCategoryInput): Promise<CategoryDef | null>;
+    /** Creates a new entity relationship, appending it to `availableEntityRelationships` on success. */
+    createEntityRelationship(item: EntityRelationshipInput): Promise<RelationshipDef | null>;
     /**
      * Lazily batch-fetch core data (label + categories) for the given entity UUIDs.
      * Already-fetched UUIDs are skipped. Populates `entityInfoMap`.

package/lib/schema.d.ts

@@ -1,6 +1,7 @@
 import { CueApi } from './api';
 import { ReadonlySignal } from './signal';
 import { CategoryDef, RelationshipDef } from './models';
+import { ContentCategoryInput, EntityCategoryInput, EntityRelationshipInput } from './semantic-template';
 /**
  * Holds the schema for a single project: available content categories,
  * entity categories, and entity relationship types.
@@ -49,7 +50,7 @@ export declare class CueProjectSchema {
      * completed (or failed). Await this before reading signal values imperatively.
      */
     readonly ready: Promise<void>;
-    constructor(_api: CueApi, _projectId: string, language: string, _graphType?: string | undefined, verbose?: boolean);
+    constructor(_api: CueApi, _projectId: string, language: string, _graphType?: "fuseki" | "qlever" | undefined, verbose?: boolean);
     /** Returns the currently active language. */
     get language(): string;
     /**
@@ -63,6 +64,33 @@ export declare class CueProjectSchema {
      * Useful when the triplestore data has changed.
      */
     refresh(): Promise<void>;
+    /**
+     * Creates a new content category via `cue.api.semanticTemplate` and, on success,
+     * appends it to {@link availableContentCategories} in place — no `refresh()`
+     * needed for it to show up in every subscriber.
+     */
+    createContentCategory(item: ContentCategoryInput): Promise<CategoryDef | null>;
+    /**
+     * Creates a new entity category via `cue.api.semanticTemplate` and, on success,
+     * appends it to {@link availableEntityCategories} in place — no `refresh()`
+     * needed for it to show up in every subscriber.
+     */
+    createEntityCategory(item: EntityCategoryInput): Promise<CategoryDef | null>;
+    /**
+     * Creates a new entity relationship via `cue.api.semanticTemplate` and, on
+     * success, appends it to {@link availableEntityRelationships} in place — no
+     * `refresh()` needed for it to show up in every subscriber.
+     */
+    createEntityRelationship(item: EntityRelationshipInput): Promise<RelationshipDef | null>;
+    /**
+     * Turns a successful create-mutation result into a {@link CategoryDef} and
+     * appends it to both the cached language-independent snapshot and the live
+     * signal. Updating `_snapshot` too (not just the signal) matters: it's what
+     * `setLanguage()`/`_apply()` re-derive from, so skipping it would make the
+     * appended item vanish on the next language switch. Returns `null` when the
+     * mutation failed (no IRI was assigned).
+     */
+    private _appendCreated;
     private _load;
     /**
      * Fetches the schema once. On QLever the pre-computed `schemas` materialized