Skip to content

Commit 7e13dbb

Browse files
pinglinpinglin
authored
refactor(artifact): align knowledge base and file resources with AIP naming (#720)
**Because** - We are aligning our resource naming with Google AIP-122 conventions, which recommend kebab-case for collection IDs (e.g., `knowledge-bases` instead of `knowledgeBases`). - We are consolidating file management and transferring ownership of namespace-level file endpoints to the Agent service. **This commit** - Renames `knowledgeBases` to `knowledge-bases` in all HTTP paths and resource patterns across `artifact/v1alpha/*.proto`. - Removes namespace-level file aliases (`/v1alpha/namespaces/*/files/**`) from `ArtifactPublicService` to allow the Agent service to manage these paths. - Updates documentation and comments to reflect the consolidated knowledge base structure. - Formats proto files for better readability and alignment with style guides.
1 parent 0663212 commit 7e13dbb

File tree

6 files changed

+144
-93
lines changed

6 files changed

+144
-93
lines changed

‎artifact/v1alpha/artifact_public_service.proto‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -121,10 +121,10 @@ service ArtifactPublicService {
121121

122122
// Create a file
123123
//
124-
// Uploads and converts a file to a knowledge base.
124+
// Uploads and converts a file.
125125
rpc CreateFile(CreateFileRequest) returns (CreateFileResponse) {
126126
option (google.api.http) = {
127-
post: "/v1alpha/{parent=namespaces/*/knowledgeBases/*}/files"
127+
post: "/v1alpha/{parent=namespaces/*/knowledge-bases/*}/files"
128128
body: "file"
129129
};
130130
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
@@ -140,7 +140,7 @@ service ArtifactPublicService {
140140
//
141141
// Returns the details of a file.
142142
rpc GetFile(GetFileRequest) returns (GetFileResponse) {
143-
option (google.api.http) = {get: "/v1alpha/{name=namespaces/*/knowledgeBases/*/files/*}"};
143+
option (google.api.http) = {get: "/v1alpha/{name=namespaces/*/knowledge-bases/*/files/*}"};
144144
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
145145
tags: "Artifact"
146146
extensions: {
@@ -152,9 +152,9 @@ service ArtifactPublicService {
152152

153153
// List files
154154
//
155-
// Returns a paginated list of files in a knowledge base.
155+
// Returns a paginated list of files.
156156
rpc ListFiles(ListFilesRequest) returns (ListFilesResponse) {
157-
option (google.api.http) = {get: "/v1alpha/{parent=namespaces/*/knowledgeBases/*}/files"};
157+
option (google.api.http) = {get: "/v1alpha/{parent=namespaces/*/knowledge-bases/*}/files"};
158158
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
159159
tags: "Artifact"
160160
extensions: {
@@ -169,7 +169,7 @@ service ArtifactPublicService {
169169
// Updates a file.
170170
rpc UpdateFile(UpdateFileRequest) returns (UpdateFileResponse) {
171171
option (google.api.http) = {
172-
patch: "/v1alpha/{file.name=namespaces/*/knowledgeBases/*/files/*}"
172+
patch: "/v1alpha/{file.name=namespaces/*/knowledge-bases/*/files/*}"
173173
body: "file"
174174
};
175175
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
@@ -187,7 +187,7 @@ service ArtifactPublicService {
187187
// This will regenerate embeddings, chunks, and summaries.
188188
rpc ReprocessFile(ReprocessFileRequest) returns (ReprocessFileResponse) {
189189
option (google.api.http) = {
190-
post: "/v1alpha/{name=namespaces/*/knowledgeBases/*/files/*}/reprocess"
190+
post: "/v1alpha/{name=namespaces/*/knowledge-bases/*/files/*}/reprocess"
191191
body: "*"
192192
};
193193
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
@@ -203,7 +203,7 @@ service ArtifactPublicService {
203203
//
204204
// Deletes a file.
205205
rpc DeleteFile(DeleteFileRequest) returns (DeleteFileResponse) {
206-
option (google.api.http) = {delete: "/v1alpha/{name=namespaces/*/knowledgeBases/*/files/*}"};
206+
option (google.api.http) = {delete: "/v1alpha/{name=namespaces/*/knowledge-bases/*/files/*}"};
207207
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
208208
tags: "Artifact"
209209
extensions: {
@@ -217,7 +217,7 @@ service ArtifactPublicService {
217217
//
218218
// Returns the details of a chunk.
219219
rpc GetChunk(GetChunkRequest) returns (GetChunkResponse) {
220-
option (google.api.http) = {get: "/v1alpha/{name=namespaces/*/knowledgeBases/*/files/*/chunks/*}"};
220+
option (google.api.http) = {get: "/v1alpha/{name=namespaces/*/knowledge-bases/*/files/*/chunks/*}"};
221221
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
222222
tags: "Artifact"
223223
extensions: {
@@ -231,7 +231,7 @@ service ArtifactPublicService {
231231
//
232232
// Returns a paginated list of chunks.
233233
rpc ListChunks(ListChunksRequest) returns (ListChunksResponse) {
234-
option (google.api.http) = {get: "/v1alpha/{parent=namespaces/*/knowledgeBases/*/files/*}/chunks"};
234+
option (google.api.http) = {get: "/v1alpha/{parent=namespaces/*/knowledge-bases/*/files/*}/chunks"};
235235
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
236236
tags: "Artifact"
237237
extensions: {
@@ -246,7 +246,7 @@ service ArtifactPublicService {
246246
// Updates a chunk.
247247
rpc UpdateChunk(UpdateChunkRequest) returns (UpdateChunkResponse) {
248248
option (google.api.http) = {
249-
patch: "/v1alpha/{name=namespaces/*/knowledgeBases/*/files/*/chunks/*}"
249+
patch: "/v1alpha/{name=namespaces/*/knowledge-bases/*/files/*/chunks/*}"
250250
body: "*"
251251
};
252252
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {

‎artifact/v1alpha/chunk.proto‎

Lines changed: 21 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,10 @@ import "google/protobuf/timestamp.proto";
1111

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

1619
// Type describes the type of a chunk content.
1720
enum Type {
@@ -34,7 +37,8 @@ message Chunk {
3437
}
3538

3639
// Field 1: The resource name of the chunk.
37-
// Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}/chunks/{chunk}`.
40+
// Format:
41+
// `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}/chunks/{chunk}`.
3842
string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
3943
// Field 2: The chunk id (unique identifier).
4044
string id = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
@@ -48,7 +52,8 @@ message Chunk {
4852
// creation time of the chunk
4953
google.protobuf.Timestamp create_time = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
5054
// The resource name of the original file this chunk belongs to.
51-
// Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}`
55+
// Format:
56+
// `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
5257
string original_file = 6 [
5358
(google.api.field_behavior) = OUTPUT_ONLY,
5459
(google.api.resource_reference) = {type: "api.instill.tech/File"}
@@ -65,7 +70,8 @@ message Chunk {
6570
// Follows AIP-132: https://google.aip.dev/132
6671
message ListChunksRequest {
6772
// The parent resource name.
68-
// Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}`
73+
// Format:
74+
// `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
6975
string parent = 1 [(google.api.field_behavior) = REQUIRED];
7076
// The maximum number of chunks to return. If this parameter is unspecified,
7177
// at most 100 chunks will be returned. The cap value for this parameter
@@ -97,7 +103,8 @@ message ListChunksResponse {
97103
// Follows AIP-131: https://google.aip.dev/131
98104
message GetChunkRequest {
99105
// The resource name of the chunk to retrieve.
100-
// Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}/chunks/{chunk}`
106+
// Format:
107+
// `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}/chunks/{chunk}`
101108
string name = 1 [(google.api.field_behavior) = REQUIRED];
102109
// Optional chunk type filter. If specified, returns a chunk of this type
103110
// from the same file. If not specified, returns the chunk identified by name.
@@ -116,7 +123,8 @@ message GetChunkResponse {
116123
// Follows AIP-134: https://google.aip.dev/134
117124
message UpdateChunkRequest {
118125
// The resource name of the chunk to update.
119-
// Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}/chunks/{chunk}`
126+
// Format:
127+
// `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}/chunks/{chunk}`
120128
string name = 1 [(google.api.field_behavior) = REQUIRED];
121129
// whether the chunk is retrievable
122130
bool retrievable = 2 [(google.api.field_behavior) = REQUIRED];
@@ -134,7 +142,7 @@ message SearchChunksRequest {
134142
// Format: `namespaces/{namespace}`
135143
string parent = 1 [(google.api.field_behavior) = REQUIRED];
136144
// The knowledge base resource name to filter by (optional).
137-
// Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}`
145+
// Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
138146
string knowledge_base = 2 [
139147
(google.api.field_behavior) = OPTIONAL,
140148
(google.api.resource_reference) = {type: "api.instill.tech/KnowledgeBase"}
@@ -153,7 +161,8 @@ message SearchChunksRequest {
153161
reserved 8;
154162
// File resource names to filter by. When this field is provided, the response
155163
// will return only chunks that belong to the specified files.
156-
// Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}`
164+
// Format:
165+
// `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
157166
repeated string files = 9 [
158167
(google.api.field_behavior) = OPTIONAL,
159168
(google.api.resource_reference) = {type: "api.instill.tech/File"}
@@ -172,7 +181,8 @@ message SearchChunksResponse {
172181
// SimilarityChunk represents a chunk with similarity score.
173182
message SimilarityChunk {
174183
// Chunk resource name.
175-
// Full resource name: namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}/chunks/{chunk}
184+
// Full resource name:
185+
// namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}/chunks/{chunk}
176186
string chunk = 1 [
177187
(google.api.field_behavior) = OUTPUT_ONLY,
178188
(google.api.resource_reference).type = "api.instill.tech/Chunk"
@@ -185,7 +195,8 @@ message SimilarityChunk {
185195
string text_content = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
186196

187197
// Source file resource name.
188-
// Full resource name: namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}
198+
// Full resource name:
199+
// namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}
189200
string file = 4 [
190201
(google.api.field_behavior) = OUTPUT_ONLY,
191202
(google.api.resource_reference).type = "api.instill.tech/File"

‎artifact/v1alpha/file.proto‎

Lines changed: 29 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,9 @@ enum ConvertedFileType {
5454
message File {
5555
option (google.api.resource) = {
5656
type: "api.instill.tech/File"
57-
pattern: "namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}"
57+
pattern:
58+
"namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/"
59+
"{file}"
5860
};
5961

6062
// View defines how a file is presented.
@@ -223,7 +225,8 @@ message File {
223225
// ===== Standard AIP fields 1-6 (ALL resources must follow this order) =====
224226

225227
// Field 1: Canonical resource name.
226-
// Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}`.
228+
// Format:
229+
// `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`.
227230
string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
228231

229232
// Field 2: Immutable canonical resource ID (80-96 bits entropy, base62).
@@ -286,7 +289,7 @@ message File {
286289
// ===== Knowledge base associations =====
287290

288291
// Knowledge base resource names that this file is associated with.
289-
// Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}`
292+
// Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
290293
// A file can belong to multiple knowledge bases within the same namespace.
291294
// This field is populated from the file_knowledge_base junction table.
292295
// Follows AIP-122 for resource name references.
@@ -359,7 +362,7 @@ message File {
359362
// Follows AIP-133: https://google.aip.dev/133
360363
message CreateFileRequest {
361364
// The parent resource name (knowledge base).
362-
// Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}`
365+
// Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
363366
string parent = 1 [(google.api.field_behavior) = REQUIRED];
364367
// The file to create.
365368
File file = 2 [(google.api.field_behavior) = OPTIONAL];
@@ -375,7 +378,8 @@ message CreateFileResponse {
375378
// Follows AIP-135: https://google.aip.dev/135
376379
message DeleteFileRequest {
377380
// The resource name of the file to delete.
378-
// Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}`
381+
// Format:
382+
// `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
379383
string name = 1 [
380384
(google.api.field_behavior) = REQUIRED,
381385
(google.api.resource_reference) = {type: "api.instill.tech/File"}
@@ -385,7 +389,8 @@ message DeleteFileRequest {
385389
// DeleteFileResponse represents a response for deleting a file.
386390
message DeleteFileResponse {
387391
// The resource name of the deleted file.
388-
// Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}`
392+
// Format:
393+
// `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
389394
string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
390395
}
391396

@@ -394,7 +399,8 @@ message DeleteFileResponse {
394399
// DeleteFileAdminRequest represents a request to delete a file (admin only).
395400
message DeleteFileAdminRequest {
396401
// The resource name of the file to delete.
397-
// Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}`
402+
// Format:
403+
// `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
398404
string name = 1 [
399405
(google.api.field_behavior) = REQUIRED,
400406
(google.api.resource_reference) = {type: "api.instill.tech/File"}
@@ -405,18 +411,21 @@ message DeleteFileAdminRequest {
405411
// only).
406412
message DeleteFileAdminResponse {
407413
// The resource name of the deleted file.
408-
// Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}`
414+
// Format:
415+
// `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
409416
string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
410417
}
411418

412-
// ReprocessFileAdminRequest represents a request to reprocess a file (admin only).
413-
// This bypasses ACL checks and triggers the ProcessFileWorkflow directly.
419+
// ReprocessFileAdminRequest represents a request to reprocess a file (admin
420+
// only). This bypasses ACL checks and triggers the ProcessFileWorkflow
421+
// directly.
414422
message ReprocessFileAdminRequest {
415423
// The file UID to reprocess.
416424
string file_uid = 1 [(google.api.field_behavior) = REQUIRED];
417425
}
418426

419-
// ReprocessFileAdminResponse represents a response for reprocessing a file (admin only).
427+
// ReprocessFileAdminResponse represents a response for reprocessing a file
428+
// (admin only).
420429
message ReprocessFileAdminResponse {
421430
// The reprocessed file.
422431
File file = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
@@ -426,7 +435,7 @@ message ReprocessFileAdminResponse {
426435
// Follows AIP-132: https://google.aip.dev/132
427436
message ListFilesRequest {
428437
// The parent resource name (knowledge base).
429-
// Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}`
438+
// Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
430439
string parent = 1 [(google.api.field_behavior) = REQUIRED];
431440
// The page size (default:10; max 100).
432441
optional int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
@@ -461,7 +470,8 @@ message ListFilesResponse {
461470
// Follows AIP-131: https://google.aip.dev/131
462471
message GetFileRequest {
463472
// The resource name of the file to retrieve.
464-
// Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}`
473+
// Format:
474+
// `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
465475
string name = 1 [
466476
(google.api.field_behavior) = REQUIRED,
467477
(google.api.resource_reference) = {type: "api.instill.tech/File"}
@@ -497,7 +507,8 @@ message GetFileResponse {
497507
// Follows AIP-134: https://google.aip.dev/134
498508
message UpdateFileRequest {
499509
// The file resource to update. The file's `name` field identifies the
500-
// resource. Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}`
510+
// resource. Format:
511+
// `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
501512
File file = 1 [(google.api.field_behavior) = REQUIRED];
502513
// The update mask specifies the subset of fields that should be modified.
503514
google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED];
@@ -512,7 +523,8 @@ message UpdateFileResponse {
512523
// ReprocessFileRequest represents a request to reprocess a file.
513524
message ReprocessFileRequest {
514525
// The resource name of the file to reprocess.
515-
// Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}`
526+
// Format:
527+
// `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
516528
string name = 1 [
517529
(google.api.field_behavior) = REQUIRED,
518530
(google.api.resource_reference) = {type: "api.instill.tech/File"}
@@ -534,7 +546,8 @@ message ReprocessFileResponse {
534546
// Follows AIP-134: https://google.aip.dev/134
535547
message UpdateFileAdminRequest {
536548
// The file resource to update. The file's `name` field identifies the
537-
// resource. Format: `namespaces/{namespace}/knowledgeBases/{knowledge_base}/files/{file}`
549+
// resource. Format:
550+
// `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
538551
File file = 1 [(google.api.field_behavior) = REQUIRED];
539552
// The update mask specifies the subset of fields that should be modified.
540553
google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED];

‎artifact/v1alpha/knowledge_base.proto‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ message KnowledgeBase {
9191

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

0 commit comments

Comments
 (0)