@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/knowledge.d.ts

@@ -0,0 +1,501 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.knowledge` (Knowledge): 21 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"assemble_knowledge_context_knowledge_context_post">;
+ *
+ * Reference with examples: knowledge.md
+ */
+/* eslint-disable */
+
+/** `g8.api.knowledge.<member>` -> the operationId it calls. */
+export interface KnowledgeMembers {
+  assembleKnowledgeContext: "assemble_knowledge_context_knowledge_context_post";
+  browseKnowledgeTree: "browse_knowledge_tree_knowledge_tree_get";
+  createAuthoredKnowledge: "create_authored_knowledge_knowledge_authored_post";
+  createAuthoredKnowledgeAmendment: "create_authored_knowledge_amendment_knowledge_authored__concept_id__amendments_post";
+  deprecateAuthoredKnowledge: "deprecate_authored_knowledge_knowledge_authored__concept_id__deprecate_post";
+  exportKnowledge: "export_knowledge_knowledge_export_get";
+  getKnowledge: "get_knowledge_knowledge__concept_id__get";
+  getKnowledgeHistory: "get_knowledge_history_knowledge__concept_id__history_get";
+  getKnowledgeStatus: "get_knowledge_status_knowledge_status_get";
+  getOntologyDeviations: "get_ontology_deviations_knowledge_ontology_deviations_get";
+  getOntologyOverview: "get_ontology_overview_knowledge_ontology_get";
+  getOntologyReadiness: "get_ontology_readiness_knowledge_ontology_readiness_get";
+  getStandardOntology: "get_standard_ontology_knowledge_ontology_standard_get";
+  knowledgeSources: "knowledge_sources_knowledge__concept_id__sources_get";
+  listKnowledge: "list_knowledge_knowledge_get";
+  listKnowledgeGovernanceQueue: "list_knowledge_governance_queue_knowledge_governance_get";
+  relatedKnowledge: "related_knowledge_knowledge__concept_id__related_get";
+  searchKnowledge: "search_knowledge_knowledge_search_get";
+  updateAuthoredKnowledgeDraft: "update_authored_knowledge_draft_knowledge_authored__concept_id__patch";
+  upsertOntologyConcept: "upsert_ontology_concept_knowledge_ontology__concept_id__put";
+  verifyAuthoredKnowledge: "verify_authored_knowledge_knowledge_authored__concept_id__verify_post";
+}
+
+/** Input and output of every `g8.api.knowledge` operation, keyed by operationId. */
+export interface KnowledgeOperations {
+  /**
+   * POST /knowledge/context
+   * Assemble Knowledge Context
+   * tier: read · scope: knowledge:read
+   */
+  assemble_knowledge_context_knowledge_context_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: KnowledgeContextRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /knowledge/tree
+   * Browse Knowledge Tree
+   * tier: read · scope: knowledge:read
+   */
+  browse_knowledge_tree_knowledge_tree_get: {
+    input: {
+    query?: {
+      /** Folder to list. Omit for the root. */
+      parent?: string | null;
+      cursor?: string | null;
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * POST /knowledge/authored
+   * Create Authored Knowledge
+   * tier: write · scope: knowledge:write
+   */
+  create_authored_knowledge_knowledge_authored_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AuthoredKnowledgeRequest;
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * POST /knowledge/authored/{concept_id}/amendments
+   * Create Authored Knowledge Amendment
+   * tier: write · scope: knowledge:write
+   */
+  create_authored_knowledge_amendment_knowledge_authored__concept_id__amendments_post: {
+    input: {
+    path: {
+      /** Concept id. */
+      concept_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AuthoredKnowledgeRequest;
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * POST /knowledge/authored/{concept_id}/deprecate
+   * Deprecate Authored Knowledge
+   * tier: write · scope: knowledge:write
+   */
+  deprecate_authored_knowledge_knowledge_authored__concept_id__deprecate_post: {
+    input: {
+    path: {
+      /** Concept id. */
+      concept_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: DeprecateKnowledgeRequest;
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * GET /knowledge/export
+   * Export Knowledge
+   * tier: read · scope: knowledge:read
+   */
+  export_knowledge_knowledge_export_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: unknown;
+  };
+  /**
+   * GET /knowledge/{concept_id}
+   * Get Knowledge
+   * tier: read · scope: knowledge:read
+   */
+  get_knowledge_knowledge__concept_id__get: {
+    input: {
+    path: {
+      concept_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /knowledge/{concept_id}/history
+   * Get Knowledge History
+   * tier: read · scope: knowledge:read
+   */
+  get_knowledge_history_knowledge__concept_id__history_get: {
+    input: {
+    path: {
+      /** Concept id. */
+      concept_id: string;
+    };
+    query?: {
+      cursor?: string | null;
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * GET /knowledge/status
+   * Get Knowledge Status
+   * tier: read · scope: knowledge:read
+   */
+  get_knowledge_status_knowledge_status_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * GET /knowledge-ontology/deviations
+   * Get Ontology Deviations
+   * tier: read · scope: knowledge:read
+   */
+  get_ontology_deviations_knowledge_ontology_deviations_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * GET /knowledge-ontology
+   * Get Ontology Overview
+   * tier: read · scope: knowledge:read
+   */
+  get_ontology_overview_knowledge_ontology_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * GET /knowledge-ontology/readiness
+   * Get Ontology Readiness
+   * tier: read · scope: knowledge:read
+   */
+  get_ontology_readiness_knowledge_ontology_readiness_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * GET /knowledge-ontology/standard
+   * Get Standard Ontology
+   * tier: read · scope: knowledge:read
+   */
+  get_standard_ontology_knowledge_ontology_standard_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * GET /knowledge/{concept_id}/sources
+   * Knowledge Sources
+   * tier: read · scope: knowledge:read
+   */
+  knowledge_sources_knowledge__concept_id__sources_get: {
+    input: {
+    path: {
+      concept_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_dict__;
+  };
+  /**
+   * GET /knowledge
+   * List Knowledge
+   * tier: read · scope: knowledge:read
+   */
+  list_knowledge_knowledge_get: {
+    input: {
+    query?: {
+      concept_type?: string | null;
+      lifecycle?: string | null;
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_dict__;
+  };
+  /**
+   * GET /knowledge-governance
+   * List Knowledge Governance Queue
+   * tier: read · scope: knowledge:read
+   */
+  list_knowledge_governance_queue_knowledge_governance_get: {
+    input: {
+    query?: {
+      /** Which governance queue to read. */
+      queue?: string;
+      /** Opaque cursor from the previous page. */
+      cursor?: string | null;
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * GET /knowledge/{concept_id}/related
+   * Related Knowledge
+   * tier: read · scope: knowledge:read
+   */
+  related_knowledge_knowledge__concept_id__related_get: {
+    input: {
+    path: {
+      concept_id: string;
+    };
+    query?: {
+      depth?: number;
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_dict__;
+  };
+  /**
+   * GET /knowledge/search
+   * Search Knowledge
+   * tier: read · scope: knowledge:read
+   */
+  search_knowledge_knowledge_search_get: {
+    input: {
+    query: {
+      query: string;
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_dict__;
+  };
+  /**
+   * PATCH /knowledge/authored/{concept_id}
+   * Update Authored Knowledge Draft
+   * tier: write · scope: knowledge:write
+   */
+  update_authored_knowledge_draft_knowledge_authored__concept_id__patch: {
+    input: {
+    path: {
+      /** Concept id. */
+      concept_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AuthoredKnowledgeRequest;
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+  /**
+   * PUT /knowledge-ontology/{concept_id}
+   * Upsert Ontology Concept
+   * tier: write · scope: knowledge:write
+   */
+  upsert_ontology_concept_knowledge_ontology__concept_id__put: {
+    input: {
+    path: {
+      concept_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: OntologyConceptRequest;
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * POST /knowledge/authored/{concept_id}/verify
+   * Verify Authored Knowledge
+   * tier: write · scope: knowledge:write
+   */
+  verify_authored_knowledge_knowledge_authored__concept_id__verify_post: {
+    input: {
+    path: {
+      /** Concept id. */
+      concept_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: VerifyKnowledgeRequest;
+  };
+    output: ApiResponse_StudioContentPayload_;
+  };
+}
+
+// 15 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_SettingsPayload_ {
+  data: SettingsPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_StudioContentPayload_ {
+  data: StudioContentPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_dict_ {
+  data: Record<string, unknown>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_dict__ {
+  data: Array<Record<string, unknown>>;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * Write a knowledge concept by hand. Spends nothing.
+ *
+ * This is the GOVERNED write path: the entry lands as a draft and moves
+ * through the review queue at `GET /knowledge/governance`. It does not
+ * project into the brain until it is approved there.
+ */
+export interface AuthoredKnowledgeRequest {
+  body: string;
+  concept_type: string;
+  owner_id?: string | null;
+  review_at?: string | null;
+  sources?: Array<SourceInput>;
+  stale_after?: string | null;
+  title: string;
+  visibility?: string;
+}
+
+/** Retire a concept. `reason` is required and is kept on the record. */
+export interface DeprecateKnowledgeRequest {
+  reason: string;
+  superseded_by?: string | null;
+}
+
+export interface KnowledgeContextRequest {
+  entity_concept_ids?: Array<string>;
+  task: string;
+  token_budget?: number | null;
+}
+
+/** Define or redefine one concept in the org's ontology. */
+export interface OntologyConceptRequest {
+  body: string;
+  concept_id: string;
+  concept_type: string;
+  definition_override?: string | null;
+  extensions?: Record<string, unknown>;
+  ontology?: Record<string, unknown>;
+  relationships?: Array<OntologyRelationship>;
+  review_at?: string | null;
+  source_owner?: string | null;
+  sources?: Array<OntologySource>;
+  /** After this, the concept is treated as stale. */
+  stale_after?: string | null;
+  /** The standard-ontology component this maps to, if any. */
+  standard_component_id?: string | null;
+  title: string;
+  /** How much to trust this definition. Defaults to human-reviewed, matching the app — a concept written through the API is treated as authored, not inferred. */
+  trust_tier?: string;
+}
+
+/** How one concept relates to another. Open-shaped, matching the app. */
+export type OntologyRelationship = Record<string, unknown>;
+
+/** Where a concept came from. Open-shaped, matching the app's `SourceInput`. */
+export type OntologySource = Record<string, unknown>;
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}
+
+/**
+ * An open envelope for a settings object.
+ *
+ * Open because an ontology concept and an SSO config both grow fields as the
+ * product does, and on a settings read a dropped field reads as "not
+ * configured" rather than "we did not tell you".
+ */
+export type SettingsPayload = Record<string, unknown>;
+
+/** A citation behind an authored concept. */
+export interface SourceInput {
+  checksum?: string | null;
+  locator?: string | null;
+  resource: string;
+  title?: string | null;
+}
+
+/** One Studio object, open-shaped. See the module docstring. */
+export type StudioContentPayload = Record<string, unknown>;
+
+/** Approve (or reject) a proposed concept, naming who vouches for it. */
+export interface VerifyKnowledgeRequest {
+  approve: boolean;
+  authority: string;
+}