syntax = "proto3";

package artifact.v1alpha;

// File definitions
import "artifact/v1alpha/file.proto";
// Google API
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
// Protocol Buffers Well-Known Types
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";
// Core definitions
import "mgmt/v1beta/mgmt.proto";

// KnowledgeBase represents a knowledge base.
// Field ordering follows AIP standard: name(1), id(2), display_name(3),
// slug(4), aliases(5), description(6)
message KnowledgeBase {
  option (google.api.resource) = {
    type: "api.instill.tech/KnowledgeBase"
    pattern: "namespaces/{namespace}/knowledge-bases/{knowledge_base}"
  };

  // EmbeddingConfig defines the embedding configuration for a knowledge base
  message EmbeddingConfig {
    // The AI model family used for embeddings (e.g., "gemini", "openai")
    string model_family = 1;
    // The dimensionality of the embedding vectors
    uint32 dimensionality = 2;
  }

  // ===== Standard AIP fields 1-6 (ALL resources must follow this order) =====

  // Field 1: Canonical resource name.
  // Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`.
  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Field 2: Immutable canonical resource ID (80-96 bits entropy, base62).
  // Example: "kb-8f3a2k9E7c1"
  string id = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Field 3: Human-readable display name for UI.
  string display_name = 3 [(google.api.field_behavior) = REQUIRED];

  // Field 4: URL-friendly slug (NO prefix).
  // If omitted, server generates from display_name.
  // If provided, server validates and persists it.
  // Slug is NOT part of resource identity.
  // Example: "my-knowledge-base"
  string slug = 4 [(google.api.field_behavior) = OPTIONAL];

  // Field 5: Previous slugs for backward compatibility.
  // When display_name changes, a new slug is generated and old slugs are stored
  // here.
  repeated string aliases = 5 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Field 6: Optional description.
  string description = 6 [(google.api.field_behavior) = OPTIONAL];

  // ===== Timestamps (common to all resources) =====

  // Field 7: Creation time.
  google.protobuf.Timestamp create_time = 7 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Field 8: Last update time.
  google.protobuf.Timestamp update_time = 8 [(google.api.field_behavior) = OUTPUT_ONLY];

  // ===== Resource-specific fields start from field 9+ =====

  // The knowledge base tags.
  repeated string tags = 9 [(google.api.field_behavior) = OPTIONAL];

  // The knowledge base type (persistent or ephemeral).
  // Default is PERSISTENT if not specified during creation.
  KnowledgeBaseType type = 10 [(google.api.field_behavior) = OPTIONAL];

  // System ID defines how the knowledge base will be created based on the
  // system's RAG configurations including:
  // - AI model family (e.g., "openai", "gemini")
  // - Embedding vector dimensionality
  // - Chunking method
  // - Other RAG-related settings
  //
  // The resource name of the system configuration.
  // Format: `systems/{system}`
  // Available systems: "systems/openai", "systems/gemini", or custom systems.
  // If not specified, defaults to the default system.
  optional string system = 11 [(google.api.field_behavior) = OPTIONAL];

  // The embedding configuration for the knowledge base.
  EmbeddingConfig embedding_config = 12 [(google.api.field_behavior) = OPTIONAL];

  // The resource name of the active Milvus collection for this knowledge base.
  // Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}/collections/{collection}`
  // This supports collection versioning for embedding dimension changes.
  string active_collection = 13 [(google.api.field_behavior) = OUTPUT_ONLY];

  // ===== Owner and creator references =====

  // Resource name of the owner namespace.
  // Example: "namespaces/usr-7k2m9p4w1n3" or "namespaces/org-3t8f5q2x6b1"
  string owner_name = 14 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Knowledge base owner (User or Organization).
  optional mgmt.v1beta.Owner owner = 15 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Full resource name of the user who created this knowledge base.
  // Format: `users/{user}`
  // Optional for system-created knowledge bases (e.g., instill-agent).
  optional string creator_name = 16 [(google.api.field_behavior) = OUTPUT_ONLY];

  // The user who created this knowledge base.
  // Populated when creator_name is present.
  optional mgmt.v1beta.User creator = 17 [(google.api.field_behavior) = OUTPUT_ONLY];

  // ===== Statistics =====

  // The total files in knowledge base.
  uint32 total_files = 18 [(google.api.field_behavior) = OUTPUT_ONLY];

  // The total tokens in knowledge base.
  uint32 total_tokens = 19 [(google.api.field_behavior) = OUTPUT_ONLY];

  // The current used storage in knowledge base.
  uint64 used_storage = 20 [(google.api.field_behavior) = OUTPUT_ONLY];

  // The downstream apps.
  repeated string downstream_apps = 21 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Knowledge Base Type. e.g. "persistent" or "ephemeral"
enum KnowledgeBaseType {
  // UNSPECIFIED
  KNOWLEDGE_BASE_TYPE_UNSPECIFIED = 0;
  // PERSISTENT
  KNOWLEDGE_BASE_TYPE_PERSISTENT = 1;
  // EPHEMERAL
  KNOWLEDGE_BASE_TYPE_EPHEMERAL = 2;
}

// CreateKnowledgeBaseRequest represents a request to create a knowledge base.
// Follows AIP-133: https://google.aip.dev/133
message CreateKnowledgeBaseRequest {
  // The parent resource name.
  // Format: `namespaces/{namespace}`
  string parent = 1 [(google.api.field_behavior) = REQUIRED];

  // The knowledge base resource to create.
  // Required fields: display_name
  // Optional fields: id (auto-generated from display_name if not provided),
  //                  description, tags, type, system_id
  KnowledgeBase knowledge_base = 2 [(google.api.field_behavior) = REQUIRED];
}

// CreateKnowledgeBaseResponse represents a response for creating a knowledge
// base.
message CreateKnowledgeBaseResponse {
  // The created knowledge base resource.
  KnowledgeBase knowledge_base = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// GetKnowledgeBaseRequest represents a request to get a knowledge base.
// Follows AIP-131: https://google.aip.dev/131
message GetKnowledgeBaseRequest {
  // The resource name of the knowledge base to retrieve.
  // Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/KnowledgeBase"}
  ];
}

// GetKnowledgeBaseResponse represents a response for getting a knowledge base.
message GetKnowledgeBaseResponse {
  // The knowledge base resource.
  KnowledgeBase knowledge_base = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// ListKnowledgeBasesRequest represents a request to list knowledge bases.
// Follows AIP-132: https://google.aip.dev/132
// Does not include ephemeral knowledge bases.
message ListKnowledgeBasesRequest {
  // The parent resource name.
  // Format: `namespaces/{namespace}`
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  // The maximum number of knowledge bases to return. If this parameter is
  // unspecified, at most 10 knowledge bases will be returned. The cap value for
  // this parameter is 100 (i.e. any value above that will be coerced to 100).
  optional int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
  // Page token for pagination.
  optional string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
  // Filter can hold an [AIP-160](https://google.aip.dev/160)-compliant filter
  // expression.
  // - `id="<knowledge_base_id>"` or `uid="<uuid>"` - Filter by specific
  // knowledge base ID/UID
  // - `q="<text>"` - Fuzzy search on knowledge base ID and description
  //
  // **Examples**:
  // - Filter by ID: `id="my-knowledge-base"`
  // - Search knowledge bases: `q="my-knowledge-base"`
  optional string filter = 4 [(google.api.field_behavior) = OPTIONAL];
}

// ListKnowledgeBasesResponse represents a response for listing knowledge bases.
message ListKnowledgeBasesResponse {
  // The list of knowledge bases.
  repeated KnowledgeBase knowledge_bases = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Next page token for pagination.
  string next_page_token = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Total number of knowledge bases matching the request.
  int32 total_size = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// UpdateKnowledgeBaseRequest represents a request to update a knowledge base.
// Follows AIP-134: https://google.aip.dev/134
message UpdateKnowledgeBaseRequest {
  // The knowledge base resource to update. The knowledge base's `name` field
  // identifies the resource.
  // Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
  KnowledgeBase knowledge_base = 1 [(google.api.field_behavior) = REQUIRED];
  // The update mask specifies the subset of fields that should be modified.
  google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED];
}

// UpdateKnowledgeBaseResponse represents a response for updating a knowledge
// base.
message UpdateKnowledgeBaseResponse {
  // The updated knowledge base resource.
  KnowledgeBase knowledge_base = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// DeleteKnowledgeBaseRequest represents a request to delete a knowledge base.
// Follows AIP-135: https://google.aip.dev/135
message DeleteKnowledgeBaseRequest {
  // The resource name of the knowledge base to delete.
  // Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/KnowledgeBase"}
  ];
}

// DeleteKnowledgeBaseResponse represents a response for deleting a knowledge
// base.
message DeleteKnowledgeBaseResponse {
  // The deleted knowledge base resource.
  KnowledgeBase knowledge_base = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// CreateKnowledgeBaseAdminRequest represents a request to create a system-level
// knowledge base without a creator (admin only).
// Follows AIP-133: https://google.aip.dev/133
message CreateKnowledgeBaseAdminRequest {
  // The parent resource name.
  // Format: `namespaces/{namespace}`
  string parent = 1 [(google.api.field_behavior) = REQUIRED];

  // The knowledge base resource to create.
  // Required fields: id (for admin, id is required rather than auto-generated)
  // Optional fields: display_name (defaults to id), description, tags, type
  KnowledgeBase knowledge_base = 2 [(google.api.field_behavior) = REQUIRED];
}

// CreateKnowledgeBaseAdminResponse represents a response for creating a
// system-level knowledge base.
message CreateKnowledgeBaseAdminResponse {
  // The created knowledge base resource.
  KnowledgeBase knowledge_base = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// ListKnowledgeBasesAdminRequest represents a request to list all knowledge
// bases in a namespace without ACL filtering (admin only).
// Follows AIP-132: https://google.aip.dev/132
message ListKnowledgeBasesAdminRequest {
  // The parent resource name.
  // Format: `namespaces/{namespace}`
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  // The maximum number of knowledge bases to return. If this parameter is
  // unspecified, at most 10 knowledge bases will be returned. The cap value for
  // this parameter is 100. Any value above 100 will be coerced to 100.
  optional int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
  // The page token, received from a previous ListKnowledgeBasesAdmin call.
  // Provide this to retrieve the subsequent page.
  optional string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
  // Optional AIP-160 filter expression. Supports:
  //   - q="<text>" for fuzzy search on display_name using pg_trgm
  optional string filter = 4 [(google.api.field_behavior) = OPTIONAL];
}

// ListKnowledgeBasesAdminResponse represents a response for listing knowledge
// bases without ACL filtering.
message ListKnowledgeBasesAdminResponse {
  // A list of knowledge bases.
  repeated KnowledgeBase knowledge_bases = 1;
  // A token that can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
  // Total number of knowledge bases.
  int32 total_size = 3;
}

// UpdateKnowledgeBaseAdminRequest represents a request to update a knowledge
// base with system-reserved tags (admin only).
// Follows AIP-134: https://google.aip.dev/134
message UpdateKnowledgeBaseAdminRequest {
  // The knowledge base resource to update. The knowledge base's `name` field
  // identifies the resource.
  // Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
  KnowledgeBase knowledge_base = 1 [(google.api.field_behavior) = REQUIRED];
  // The update mask specifies the subset of fields that should be modified.
  google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED];
}

// UpdateKnowledgeBaseAdminResponse represents a response for updating a
// knowledge base.
message UpdateKnowledgeBaseAdminResponse {
  // The updated knowledge base resource.
  KnowledgeBase knowledge_base = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// ResetKnowledgeBaseEmbeddingsAdminRequest represents a request to reset all
// embeddings for a knowledge base (admin only).
message ResetKnowledgeBaseEmbeddingsAdminRequest {
  // The resource name of the knowledge base to reset embeddings for.
  // Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/KnowledgeBase"}
  ];
}

// ResetKnowledgeBaseEmbeddingsAdminResponse represents a response for resetting
// knowledge base embeddings.
message ResetKnowledgeBaseEmbeddingsAdminResponse {
  // The knowledge base that had its embeddings reset.
  KnowledgeBase knowledge_base = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Number of files that will be re-embedded.
  int32 files_to_reembed = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// MoveFilesToKnowledgeBaseAdminRequest represents a request to move files from
// source knowledge bases to a target knowledge base (admin only).
// Adds file associations to a knowledge base (admin only).
// Files can belong to multiple KBs (many-to-many relationship).
message AddFilesToKnowledgeBaseAdminRequest {
  // The resource name of the target knowledge base to add files to.
  // Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
  string target_knowledge_base = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/KnowledgeBase"}
  ];
  // The resource names of files to add to the target knowledge base.
  // Format: `namespaces/{namespace}/files/{file}`
  // Files that already exist in the target KB are skipped (no duplicates).
  repeated string files = 2 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/File"}
  ];
}

// AddFilesToKnowledgeBaseAdminResponse represents a response for adding files.
message AddFilesToKnowledgeBaseAdminResponse {
  // Number of files added to the target knowledge base.
  int32 files_added = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// DeleteKnowledgeBaseAdminRequest represents a request to delete a knowledge
// base (admin only). This force deletes the KB even if it contains files.
// Files are NOT deleted - they remain orphaned (no KB association).
message DeleteKnowledgeBaseAdminRequest {
  // The resource name of the knowledge base to delete.
  // Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/KnowledgeBase"}
  ];
}

// DeleteKnowledgeBaseAdminResponse represents a response for deleting a KB.
message DeleteKnowledgeBaseAdminResponse {
  // Empty response on success.
}

// ListFilesAdminRequest represents a request to list files in a knowledge base
// (admin only, bypasses ACL checks).
message ListFilesAdminRequest {
  // The resource name of the knowledge base.
  // Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/KnowledgeBase"}
  ];
  // Maximum number of files to return. Default is 100.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
  // Page token for pagination.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
  // AIP-160 filter expression. Supports the same syntax as the public ListFiles API.
  // Examples:
  //   - `id="file-abc123"` - filter by hash-based file ID
  //   - `tags:"agent:collection:col-xxx"` - filter by tag
  //   - `q="aws"` - fuzzy search on file display name, ID, and description
  //   - `(id="file-a" OR id="file-b") AND tags:"mytag"` - compound filter
  string filter = 4 [(google.api.field_behavior) = OPTIONAL];

  // View allows trusted admin callers to request an explicit file view so
  // that each returned `File` carries a populated `derived_resource_uri`
  // (see `File.derived_resource_uri`). Mirrors `ListFilesRequest.view`;
  // forwarded to the underlying CE public handler verbatim. Unset leaves
  // `derived_resource_uri` empty for every row.
  optional File.View view = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional permission filter compiled into the SQL WHERE clause alongside
  // pagination. When present, both the returned files and total_size reflect
  // only rows that satisfy at least one clause (OR semantics across clauses,
  // AND semantics within a clause). When absent, no permission narrowing is
  // applied and the query returns all files the AIP-160 filter matches.
  //
  // Callers are responsible for computing the clauses (e.g. from an
  // authorization system); the server treats them as opaque predicates.
  repeated FilePermissionClause permission_clauses = 6 [(google.api.field_behavior) = OPTIONAL];
}

// FilePermissionClause is a single conjunction of predicates. Within a clause,
// every populated field must hold (AND). Across clauses in the request, the
// semantics are OR: a file passes if it satisfies any one clause.
//
// Each field maps to a PostgreSQL predicate on the `file` table. Empty /
// absent fields are ignored (not applied as a predicate).
message FilePermissionClause {
  // Match files whose `tags` column overlaps with the supplied set.
  // SQL: `file.tags && $tags_overlap` (PostgreSQL array-overlap operator).
  repeated string tags_overlap = 1;

  // Match files whose primary UID is in the supplied set.
  // SQL: `file.uid = ANY($uids_in)`.
  repeated string uids_in = 2;

  // Exclude files that have any tag matching the supplied LIKE patterns.
  // SQL: `NOT EXISTS (SELECT 1 FROM unnest(file.tags) t WHERE t LIKE $pattern)`
  // for each pattern.
  repeated string tags_like_none = 3;

  // Match files whose `visibility` column is in the supplied set.
  // SQL: `file.visibility = ANY($visibility_in)`.
  repeated string visibility_in = 4;

  // Match files whose `parent_folder_uid` column is in the supplied set —
  // the folder the file lives directly in. Used by the folder-cascade
  // permission path: the prefilter pushes down "files whose parent folder
  // is in the caller's set of readable folders".
  // SQL: `file.parent_folder_uid = ANY($parent_folder_uid_in)`.
  repeated string parent_folder_uid_in = 5;
}

// ListFilesAdminResponse represents a response for listing files (admin only).
message ListFilesAdminResponse {
  // The files in the knowledge base.
  repeated File files = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Token for the next page.
  string next_page_token = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Total number of files.
  int32 total_size = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
}