syntax = "proto3";

package artifact.v1alpha;

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/timestamp.proto";

// The Chunk message represents a chunk of data in the artifact system.
message Chunk {
  option (google.api.resource) = {pattern:
      "namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/"
      "{file}/chunks/{chunk}"
};

  // Type describes the type of a chunk content.
  enum Type {
    // Unspecified.
    TYPE_UNSPECIFIED = 0;
    // Content.
    TYPE_CONTENT = 1;
    // Summary.
    TYPE_SUMMARY = 2;
    // Augmented.
    TYPE_AUGMENTED = 3;
  }

  // Reference represents the position of a chunk within a file.
  message Reference {
    // Start position of the chunk within the file.
    File.Position start = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
    // End position of the chunk within the file.
    File.Position end = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // Field 1: The resource name of the chunk.
  // Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}/chunks/{chunk}`.
  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Field 2: The chunk id (unique identifier).
  string id = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

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

  // whether the chunk is retrievable
  bool retrievable = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
  // tokens of the chunk
  uint32 tokens = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
  // creation time of the chunk
  google.protobuf.Timestamp create_time = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
  // The resource name of the original file this chunk belongs to.
  // Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
  string original_file = 6 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = {type: "api.instill.tech/File"}
  ];
  // chunk type
  Type type = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Reference to the position of the chunk within the original file.
  Reference reference = 8 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Reference to the position of the chunk within the Markdown (source) file.
  Reference markdown_reference = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// ListChunksRequest represents a request to list chunks in the artifact system.
// Follows AIP-132: https://google.aip.dev/132
message ListChunksRequest {
  // The parent resource name.
  // Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  // The maximum number of chunks to return. If this parameter is unspecified,
  // at most 100 chunks will be returned. The cap value for this parameter
  // is 1000 (i.e. any value above that will be coerced to 1000).
  optional int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
  // Page token.
  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="<uuid>"` or `uid="<uuid>"` - Filter by specific chunk ID/UID
  // - `chunk_type="CHUNK_TYPE_TEXT"` - Filter by chunk type
  // - `retrievable=true` - Filter by retrievable status
  //
  // **Examples**:
  // - List specific chunks: `id="uuid1" OR id="uuid2"`
  // - List text chunks: `chunk_type="CHUNK_TYPE_TEXT"`
  // - List retrievable chunks: `retrievable=true`
  optional string filter = 4 [(google.api.field_behavior) = OPTIONAL];
}

// ListChunksResponse represents a response containing a list of chunks in the
// artifact system.
message ListChunksResponse {
  // repeated chunks
  repeated Chunk chunks = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// GetChunkRequest represents a request to get a chunk.
// Follows AIP-131: https://google.aip.dev/131
message GetChunkRequest {
  // The resource name of the chunk to retrieve.
  // Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}/chunks/{chunk}`
  string name = 1 [(google.api.field_behavior) = REQUIRED];
  // Optional chunk type filter. If specified, returns a chunk of this type
  // from the same file. If not specified, returns the chunk identified by name.
  optional Chunk.Type chunk_type = 2 [(google.api.field_behavior) = OPTIONAL];
}

// GetChunkResponse represents a response for getting a chunk.
message GetChunkResponse {
  // The chunk metadata, including markdown_reference for extracting content.
  // Clients should use GetFile to fetch the full content/summary markdown,
  // then use markdown_reference coordinates to extract the specific chunk text.
  Chunk chunk = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// UpdateChunkRequest represents a request to update a chunk.
// Follows AIP-134: https://google.aip.dev/134
message UpdateChunkRequest {
  // The resource name of the chunk to update.
  // Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}/chunks/{chunk}`
  string name = 1 [(google.api.field_behavior) = REQUIRED];
  // whether the chunk is retrievable
  bool retrievable = 2 [(google.api.field_behavior) = REQUIRED];
}

// UpdateChunkResponse represents a response for updating a chunk.
message UpdateChunkResponse {
  // chunk
  Chunk chunk = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// SearchChunksRequest represents a request to search for similar chunks.
message SearchChunksRequest {
  // The parent resource name (namespace).
  // Format: `namespaces/{namespace}`
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  // The knowledge base resource name to filter by (optional).
  // Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
  string knowledge_base = 2 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.resource_reference) = {type: "api.instill.tech/KnowledgeBase"}
  ];
  // Text prompt to look for similarities.
  string text_prompt = 3 [(google.api.field_behavior) = REQUIRED];
  // Top K. Default value: 5.
  uint32 top_k = 4 [(google.api.field_behavior) = OPTIONAL];
  // 5 is reserved for file_name, deprecated by file_uid.
  reserved 5;
  // Chunk type.
  Chunk.Type type = 6 [(google.api.field_behavior) = OPTIONAL];
  // File media type.
  File.FileMediaType file_media_type = 7 [(google.api.field_behavior) = OPTIONAL];
  // 8 is reserved for file_uid, deprecated by file_uids.
  reserved 8;
  // File resource names to filter by. When this field is provided, the response
  // will return only chunks that belong to the specified files.
  // Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
  repeated string files = 9 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.resource_reference) = {type: "api.instill.tech/File"}
  ];
  // Tags to filter by. When multiple tags are provided, OR logic is applied.
  // Note: File filter takes precedence over tags, as tags apply to files.
  repeated string tags = 10 [(google.api.field_behavior) = OPTIONAL];
  // When true, results are grouped by file so that no single file dominates
  // the result set. At most group_size chunks are returned per file.
  bool group_by_file = 11 [(google.api.field_behavior) = OPTIONAL];
  // Max chunks per file when group_by_file is true. Default: 1.
  int32 group_size = 12 [(google.api.field_behavior) = OPTIONAL];
}

// Ranker identifies which Milvus hybrid-search reranker produced the
// scores on a `SearchChunksResponse`. The score distribution depends on
// the reranker, and downstream consumers that apply score-based
// thresholds MUST read this field so they can pick the correct floor
// shape (absolute [0,1] floor for `RANKER_WEIGHTED`; rank-structural
// `1/(k+topK)` floor for `RANKER_RRF`).
enum Ranker {
  // RANKER_UNSPECIFIED is the default zero value and indicates the
  // server did not populate the field. Treat it as "unknown" — do not
  // apply ranker-specific floor logic.
  RANKER_UNSPECIFIED = 0;
  // RANKER_WEIGHTED is Milvus' WeightedRanker (dense + BM25 combined
  // with static weights); scores are normalised to [0,1].
  RANKER_WEIGHTED = 1;
  // RANKER_RRF is Reciprocal Rank Fusion with smoothing constant k
  // (Milvus default 60); scores live in (0, 2/(k+1)].
  RANKER_RRF = 2;
}

// SearchChunksResponse represents a response for searching similar chunks.
message SearchChunksResponse {
  // chunks
  repeated SimilarityChunk similar_chunks = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  // The reranker that produced the scores in `similar_chunks`. Read
  // this before applying any score threshold — see the `Ranker` enum
  // for why.
  Ranker ranker = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// SimilarityChunk represents a chunk with similarity score.
message SimilarityChunk {
  // Chunk resource name.
  // Full resource name:
  // namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}/chunks/{chunk}
  string chunk = 1 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference).type = "api.instill.tech/Chunk"
  ];

  // Similarity score.
  float similarity_score = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Content.
  string text_content = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Source file resource name.
  // Full resource name:
  // namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}
  string file = 4 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference).type = "api.instill.tech/File"
  ];

  // Chunk metadata.
  Chunk chunk_metadata = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
}