WIP file set annotation route

Author: kdid

api/src/handlers/get-file-set-annotations.js

@@ -0,0 +1,33 @@
+const { wrap } = require("./middleware");
+const { getFileSet } = require("../api/opensearch");
+const { appInfo } = require("../environment");
+const opensearchResponse = require("../api/response/opensearch");
+
+/**
+ * Returns annotations for a FileSet
+ */
+exports.handler = wrap(async (event) => {
+  const id = event.pathParameters.id;
+  const allowPrivate =
+    event.userToken.isSuperUser() || event.userToken.isReadingRoom();
+  const allowUnpublished = event.userToken.isSuperUser();
+
+  const esResponse = await getFileSet(id, { allowPrivate, allowUnpublished });
+  if (esResponse.statusCode !== 200) {
+    return await opensearchResponse.transform(esResponse);
+  }
+
+  const body = JSON.parse(esResponse.body);
+  const annotations = body?._source?.annotations ?? null;
+
+  return {
+    statusCode: 200,
+    headers: {
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({
+      data: annotations,
+      info: appInfo(),
+    }),
+  };
+});

api/template.yaml

@@ -334,6 +334,30 @@ Resources:
             ApiId: !Ref dcApi
             Path: /file-sets/{id}
             Method: HEAD
+  getFileSetAnnotationsFunction:
+    Type: AWS::Serverless::Function
+    Condition: DeployAPI
+    Properties:
+      Handler: handlers/get-file-set-annotations.handler
+      Description: Gets annotations for a FileSet.
+      #* Layers:
+      #*   - !Ref apiDependencies
+      Policies:
+        - !Ref SecretsPolicy
+        - !Ref readIndexPolicy
+      Events:
+        ApiGet:
+          Type: HttpApi
+          Properties:
+            ApiId: !Ref dcApi
+            Path: /file-sets/{id}/annotations
+            Method: GET
+        ApiHead:
+          Type: HttpApi
+          Properties:
+            ApiId: !Ref dcApi
+            Path: /file-sets/{id}/annotations
+            Method: HEAD
   getFileSetAuthFunction:
     Type: AWS::Serverless::Function
     Condition: DeployAPI
@@ -969,4 +993,4 @@ Resources:
               </table>
               <!--[if gte mso 15]></td></tr></table><![endif]-->
             </body>
-          </html>
+          </html>

api/test/fixtures/mocks/fileset-annotated-1234.json

@@ -0,0 +1,23 @@
+{
+  "_index": "dev-dc-v2-file-set",
+  "_type": "_doc",
+  "_id": "1234",
+  "_version": 1,
+  "found": true,
+  "_source": {
+    "id": "1234",
+    "api_model": "FileSet",
+    "visibility": "Public",
+    "published": true,
+    "mime_type": "audio/mpeg",
+    "annotations": [
+      {
+        "id": "36a47020-5410-4dda-a7ca-967fe3885bcd",
+        "type": "transcription",
+        "language": ["lg", "en"],
+        "content": "ABAVUBI N'ABAKOLA EMIRIMU EGYEKUUSA KU KUVUBA TWENYIGIRE MU KUZIYIZA AKAWUKA AKALEETA SIRIIMU\n\nWuumira imo mukyala esezenga ye tituufu obuseero bwe bojja twekebezze, otte nobujjuuirizi ayeibuli\n\nMUSONZI LC\n\nMwami eno naffe Tubye twekebezza ekwanke ku kuvuba, kyokka tusobola otulunge emirinu ayeffe.\n\nLAKE VICTORIA FISHERIES ORGANISATION OF THE EAST AFRICAN COMMUNITY (LVFO)\nFIGHTING VECTOR-BORNE DISEASES\nPROMOTED GOOD ENVIRONMENTAL\n\nKALANGALA DISTRICT FORUM OF PEOPLE LIVING WITH HIV/AIDS HAS NO MORE (KADIFOHM)\nTHE LIFE YOU SAVE IS YOUR OWN\nUnited for a positive difference",
+        "model": "us.anthropic.claude-sonnet-4-5-20250929-v1:0"
+      }
+    ]
+  }
+}

api/test/integration/get-doc.test.js

@@ -169,6 +169,43 @@ describe("Doc retrieval routes", () => {
     });
   });
 
+  describe("GET /file-sets/{id}/annotations", () => {
+    const { handler } = requireSource("handlers/get-file-set-annotations");
+
+    it("returns annotations for a file-set", async () => {
+      mock
+        .get("/dc-v2-file-set/_doc/1234")
+        .reply(200, helpers.testFixture("mocks/fileset-annotated-1234.json"));
+
+      const event = helpers
+        .mockEvent("GET", "/file-sets/{id}/annotations")
+        .pathParams({ id: 1234 })
+        .render();
+      const result = await handler(event);
+      expect(result.statusCode).to.eq(200);
+
+      const body = JSON.parse(result.body);
+      expect(body.data).to.be.an("array").with.lengthOf(1);
+      expect(body.data[0].type).to.eq("transcription");
+    });
+
+    it("returns null when no annotations exist", async () => {
+      mock
+        .get("/dc-v2-file-set/_doc/1234")
+        .reply(200, helpers.testFixture("mocks/fileset-1234.json"));
+
+      const event = helpers
+        .mockEvent("GET", "/file-sets/{id}/annotations")
+        .pathParams({ id: 1234 })
+        .render();
+      const result = await handler(event);
+      expect(result.statusCode).to.eq(200);
+
+      const body = JSON.parse(result.body);
+      expect(body.data).to.eq(null);
+    });
+  });
+
   describe("Superuser", () => {
     helpers.saveEnvironment();
     let event;

chat/dependencies/requirements.txt

@@ -0,0 +1,190 @@
+# This file was autogenerated by uv via the following command:
+#    uv export --format requirements-txt --no-hashes
+annotated-types==0.7.0
+    # via pydantic
+anyio==4.11.0
+    # via
+    #   httpx
+    #   openai
+boto3==1.40.47
+    # via
+    #   dc-api-v2-chat
+    #   langchain-aws
+botocore==1.40.47
+    # via
+    #   boto3
+    #   s3transfer
+certifi==2025.10.5
+    # via
+    #   httpcore
+    #   httpx
+    #   opensearch-py
+    #   requests
+charset-normalizer==3.4.3
+    # via requests
+colorama==0.4.6 ; sys_platform == 'win32'
+    # via tqdm
+distro==1.9.0
+    # via openai
+events==0.5
+    # via opensearch-py
+greenlet==3.2.4 ; (python_full_version < '3.14' and platform_machine == 'AMD64') or (python_full_version < '3.14' and platform_machine == 'WIN32') or (python_full_version < '3.14' and platform_machine == 'aarch64') or (python_full_version < '3.14' and platform_machine == 'amd64') or (python_full_version < '3.14' and platform_machine == 'ppc64le') or (python_full_version < '3.14' and platform_machine == 'win32') or (python_full_version < '3.14' and platform_machine == 'x86_64')
+    # via sqlalchemy
+h11==0.16.0
+    # via httpcore
+honeybadger==0.23.1
+    # via dc-api-v2-chat
+httpcore==1.0.9
+    # via httpx
+httpx==0.28.1
+    # via
+    #   langgraph-sdk
+    #   langsmith
+    #   openai
+idna==3.10
+    # via
+    #   anyio
+    #   httpx
+    #   requests
+jiter==0.11.0
+    # via openai
+jmespath==1.0.1
+    # via
+    #   boto3
+    #   botocore
+jsonpatch==1.33
+    # via langchain-core
+jsonpointer==3.0.0
+    # via jsonpatch
+langchain==0.3.27
+    # via dc-api-v2-chat
+langchain-aws==0.2.35
+    # via dc-api-v2-chat
+langchain-core==0.3.78
+    # via
+    #   langchain
+    #   langchain-aws
+    #   langchain-openai
+    #   langchain-text-splitters
+    #   langgraph
+    #   langgraph-checkpoint
+    #   langgraph-prebuilt
+langchain-openai==0.3.35
+    # via dc-api-v2-chat
+langchain-text-splitters==0.3.11
+    # via langchain
+langgraph==0.6.8
+    # via dc-api-v2-chat
+langgraph-checkpoint==2.1.2
+    # via
+    #   langgraph
+    #   langgraph-prebuilt
+langgraph-prebuilt==0.6.4
+    # via langgraph
+langgraph-sdk==0.2.9
+    # via langgraph
+langsmith==0.4.33
+    # via
+    #   langchain
+    #   langchain-core
+numpy==2.2.6
+    # via
+    #   dc-api-v2-chat
+    #   langchain-aws
+openai==1.109.1
+    # via
+    #   dc-api-v2-chat
+    #   langchain-openai
+opensearch-py==2.8.0
+    # via dc-api-v2-chat
+orjson==3.11.3
+    # via
+    #   langgraph-sdk
+    #   langsmith
+ormsgpack==1.10.0
+    # via langgraph-checkpoint
+packaging==25.0
+    # via
+    #   langchain-core
+    #   langsmith
+psutil==7.1.0
+    # via honeybadger
+pydantic==2.12.0
+    # via
+    #   langchain
+    #   langchain-aws
+    #   langchain-core
+    #   langgraph
+    #   langsmith
+    #   openai
+pydantic-core==2.41.1
+    # via pydantic
+pyjwt==2.6.0
+    # via dc-api-v2-chat
+python-dateutil==2.9.0.post0
+    # via
+    #   botocore
+    #   opensearch-py
+python-dotenv==1.0.1
+    # via dc-api-v2-chat
+pyyaml==6.0.3
+    # via
+    #   langchain
+    #   langchain-core
+regex==2025.9.18
+    # via tiktoken
+requests==2.32.5
+    # via
+    #   dc-api-v2-chat
+    #   langchain
+    #   langsmith
+    #   opensearch-py
+    #   requests-aws4auth
+    #   requests-toolbelt
+    #   tiktoken
+requests-aws4auth==1.3.1
+    # via dc-api-v2-chat
+requests-toolbelt==1.0.0
+    # via langsmith
+s3transfer==0.14.0
+    # via boto3
+six==1.17.0
+    # via
+    #   honeybadger
+    #   python-dateutil
+sniffio==1.3.1
+    # via
+    #   anyio
+    #   openai
+sqlalchemy==2.0.43
+    # via langchain
+tenacity==9.1.2
+    # via langchain-core
+tiktoken==0.11.0
+    # via
+    #   dc-api-v2-chat
+    #   langchain-openai
+tqdm==4.67.1
+    # via openai
+typing-extensions==4.15.0
+    # via
+    #   anyio
+    #   langchain-core
+    #   openai
+    #   pydantic
+    #   pydantic-core
+    #   sqlalchemy
+    #   typing-inspection
+typing-inspection==0.4.2
+    # via pydantic
+urllib3==2.5.0
+    # via
+    #   botocore
+    #   opensearch-py
+    #   requests
+wheel==0.45.1
+    # via dc-api-v2-chat
+xxhash==3.6.0
+    # via langgraph
+zstandard==0.25.0
+    # via langsmith

docs/docs/spec/openapi.yaml

@@ -168,6 +168,16 @@ paths:
       responses:
         200:
           $ref: "./types.yaml#/components/responses/DocumentResponse"
+  /file-sets/{id}/annotations:
+    get:
+      operationId: getFileSetAnnotations
+      tags:
+        - FileSet
+      parameters:
+        - $ref: "./types.yaml#/components/parameters/id"
+      responses:
+        200:
+          $ref: "./types.yaml#/components/responses/AnnotationsResponse"
   /file-sets/{id}/authorization:
     get:
       operationId: getFileSetAuth

docs/docs/spec/types.yaml

@@ -115,6 +115,20 @@ components:
                 $ref: "#/components/schemas/IndexDocument"
               info:
                 type: object
+    AnnotationsResponse:
+      description: Annotations for a FileSet
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: array
+                items:
+                  $ref: "./data-types.yaml#/components/schemas/Annotation"
+                nullable: true
+              info:
+                $ref: "./data-types.yaml#/components/schemas/Info"
     SearchResponse:
       description: A page of search results
       content: