read from the shared client

seems to be missing one little `v`

CONTRIBUTING.md

@@ -18,7 +18,7 @@ versions need to be kept consistent to sidecar it with `llama_cloud_services`. B
 
 You can also do this with `./scripts/version-bump.py set 0.x.x` if you have `uv` installed.
 
-Once the change is merged, push a tag `git tag -a v0.x.x -m 0.x.x` and `git push origin 0.x.x`.
+Once the change is merged, push a tag `git tag -a v0.x.x -m 0.x.x` and `git push origin v0.x.x`.
 
 This tagging step can be done with `./scripts/version-bump tag`.
 

examples/README.md

@@ -5,5 +5,6 @@ In this folder you will find several python notebooks that contain examples rega
 - [LlamaParse](./parse/)
 - [LlamaExtract](./extract/)
 - [LlamaReport](./report/)
+- [LlamaCloudIndex](./index/)
 
 Follow the instructions in each notebook to get started!

examples/parse/demo_excel.ipynb

@@ -43,7 +43,7 @@
    "source": [
     "from llama_cloud_services import LlamaParse\n",
     "\n",
-    "api_key = \"llx-jwAQZL8T38onyL9hKBOXyRtnuCU0Fk3z7tmDhIT3L0GEfohJ\"  # get from cloud.llamaindex.ai"
+    "api_key = \"llx-...\"  # get from cloud.llamaindex.ai"
    ]
   },
   {

examples/parse/excel/dcf_rag.ipynb

@@ -75,7 +75,6 @@
     "    adaptive_long_table=True,\n",
     "    outlined_table_extraction=True,\n",
     "    output_tables_as_HTML=True,\n",
-    "    api_key=\"llx-jwAQZL8T38onyL9hKBOXyRtnuCU0Fk3z7tmDhIT3L0GEfohJ\",\n",
     ")\n",
     "\n",
     "result = await parser.aparse(\"./dcf_template.xlsx\")\n",

py/llama_cloud_services/__init__.py

@@ -1,6 +1,6 @@
 from llama_cloud_services.parse import LlamaParse
 from llama_cloud_services.report import ReportClient, LlamaReport
-from llama_cloud_services.extract import LlamaExtract, ExtractionAgent
+from llama_cloud_services.extract import LlamaExtract, ExtractionAgent, SourceText
 from llama_cloud_services.constants import EU_BASE_URL
 from llama_cloud_services.index import (
     LlamaCloudCompositeRetriever,
@@ -14,6 +14,7 @@ __all__ = [
     "LlamaReport",
     "LlamaExtract",
     "ExtractionAgent",
+    "SourceText",
     "EU_BASE_URL",
     "LlamaCloudIndex",
     "LlamaCloudRetriever",

py/llama_cloud_services/beta/classifier/client.py

@@ -17,6 +17,9 @@ from llama_cloud_services.files.client import FileClient
 from llama_cloud_services.constants import POLLING_TIMEOUT_SECONDS
 from llama_cloud_services.utils import is_terminal_status, augment_async_errors
 from llama_index.core.async_utils import DEFAULT_NUM_WORKERS, run_jobs
+from llama_cloud_services.beta.classifier.types import (
+    ClassifyJobResultsWithFiles,
+)
 
 
 class ClassificationOutput(BaseModel):
@@ -52,6 +55,24 @@ class ClassifyClient:
         self.file_client = FileClient(client, project_id, organization_id)
         self.polling_timeout = polling_timeout
 
+    @classmethod
+    def from_api_key(
+        cls,
+        api_key: str,
+        project_id: Optional[str] = None,
+        organization_id: Optional[str] = None,
+        base_url: Optional[str] = None,
+    ) -> "ClassifyClient":
+        """
+        Create a classify client from an API key.
+        """
+        client = AsyncLlamaCloud(token=api_key, base_url=base_url)
+        return cls(
+            client,
+            project_id,
+            organization_id,
+        )
+
     async def acreate_classify_job(
         self,
         rules: list[ClassifierRule],
@@ -152,11 +173,12 @@ class ClassifyClient:
         file_input_path: str,
         parsing_configuration: Optional[ClassifyParsingConfiguration] = None,
         raise_on_error: bool = True,
-    ) -> ClassifyJobResults:
+    ) -> ClassifyJobResultsWithFiles:
         file = await self.file_client.upload_file(file_input_path)
-        return await self.aclassify_file_ids(
+        results = await self.aclassify_file_ids(
             rules, [file.id], parsing_configuration, raise_on_error
         )
+        return ClassifyJobResultsWithFiles.from_classify_job_results(results, [file])
 
     def classify_file_path(
         self,
@@ -164,7 +186,7 @@ class ClassifyClient:
         file_input_path: str,
         parsing_configuration: Optional[ClassifyParsingConfiguration] = None,
         raise_on_error: bool = True,
-    ) -> ClassifyJobResults:
+    ) -> ClassifyJobResultsWithFiles:
         with augment_async_errors():
             return asyncio.run(
                 self.aclassify_file_path(
@@ -180,7 +202,7 @@ class ClassifyClient:
         raise_on_error: bool = True,
         workers: int = DEFAULT_NUM_WORKERS,
         show_progress: bool = False,
-    ) -> ClassifyJobResults:
+    ) -> ClassifyJobResultsWithFiles:
         coroutines = [self.file_client.upload_file(path) for path in file_input_paths]
         files: list[File] = await run_jobs(
             coroutines,
@@ -188,9 +210,10 @@ class ClassifyClient:
             workers=workers,
             desc="Uploading files for classification",
         )
-        return await self.aclassify_file_ids(
+        results = await self.aclassify_file_ids(
             rules, [file.id for file in files], parsing_configuration, raise_on_error
         )
+        return ClassifyJobResultsWithFiles.from_classify_job_results(results, files)
 
     def classify_file_paths(
         self,
@@ -198,7 +221,7 @@ class ClassifyClient:
         file_input_paths: list[str],
         parsing_configuration: Optional[ClassifyParsingConfiguration] = None,
         raise_on_error: bool = True,
-    ) -> ClassifyJobResults:
+    ) -> ClassifyJobResultsWithFiles:
         with augment_async_errors():
             return asyncio.run(
                 self.aclassify_file_paths(

py/llama_cloud_services/beta/classifier/types.py

@@ -0,0 +1,59 @@
+from llama_cloud.types.classify_job_results import ClassifyJobResults
+from llama_cloud.types.file_classification import FileClassification
+from llama_cloud.types.file import File
+
+
+class FileClassificationWithFile(FileClassification):
+    """
+    File classification with file object.
+    """
+
+    file: File
+
+    @classmethod
+    def from_file_classification(
+        cls, file_classification: FileClassification, file: File
+    ) -> "FileClassificationWithFile":
+        if file_classification.file_id != file.id:
+            raise ValueError(
+                f"File classification ID {file_classification.id} does not match file ID {file.id}"
+            )
+        ctor_args = {
+            **file_classification.dict(),
+            "file": file,
+        }
+        return cls(**ctor_args)
+
+
+class ClassifyJobResultsWithFiles(ClassifyJobResults):
+    """
+    Classify job results with file objects.
+    """
+
+    items: list[FileClassificationWithFile]
+
+    @classmethod
+    def from_classify_job_results(
+        cls, classify_job_results: ClassifyJobResults, files: list[File]
+    ) -> "ClassifyJobResultsWithFiles":
+        if len(classify_job_results.items) != len(files):
+            raise ValueError(
+                f"Number of classify job results {len(classify_job_results.items)} does not match number of files {len(files)}"
+            )
+        # create mapping of file classification result to file object
+        file_id_to_file: dict[str, File] = {file.id: file for file in files}
+        file_classification_to_file: list[tuple[FileClassification, File]] = []
+        for item in classify_job_results.items:
+            if item.file_id not in file_id_to_file:
+                raise ValueError(
+                    f"File classification result {item.id} has file ID {item.file_id} that does not match any provided file ID"
+                )
+            file_classification_to_file.append((item, file_id_to_file[item.file_id]))
+
+        # create a list of file classification with file objects
+        ctor_args = classify_job_results.dict()
+        ctor_args["items"] = [
+            FileClassificationWithFile.from_file_classification(item, file)
+            for item, file in file_classification_to_file
+        ]
+        return cls(**ctor_args)

py/llama_parse/pyproject.toml

@@ -11,13 +11,13 @@ dev = [
 
 [project]
 name = "llama-parse"
-version = "0.6.62"
+version = "0.6.63"
 description = "Parse files into RAG-Optimized formats."
 authors = [{name = "Logan Markewich", email = "logan@llamaindex.ai"}]
 requires-python = ">=3.9,<4.0"
 readme = "README.md"
 license = "MIT"
-dependencies = ["llama-cloud-services>=0.6.62"]
+dependencies = ["llama-cloud-services>=0.6.63"]
 
 [project.scripts]
 llama-parse = "llama_parse.cli.main:parse"

py/pyproject.toml

@@ -19,7 +19,7 @@ dev = [
 
 [project]
 name = "llama-cloud-services"
-version = "0.6.62"
+version = "0.6.63"
 description = "Tailored SDK clients for LlamaCloud services."
 authors = [{name = "Logan Markewich", email = "logan@runllama.ai"}]
 requires-python = ">=3.9,<4.0"

py/tests/classifier/test_client.py

@@ -2,6 +2,7 @@ import os
 import pytest
 from llama_cloud.client import AsyncLlamaCloud
 from llama_cloud.types import Project, ClassifierRule, ClassifyJobResults
+from llama_cloud_services.beta.classifier.types import ClassifyJobResultsWithFiles
 from llama_cloud_services.beta.classifier.client import ClassifyClient
 from llama_cloud_services.files.client import FileClient
 from llama_cloud.errors.unprocessable_entity_error import UnprocessableEntityError
@@ -130,6 +131,44 @@ async def test_classify_file_ids(
         assert item.result.type == expected_type
 
 
+@pytest.mark.asyncio
+async def test_classify_file_ids_from_api_key(
+    e2e_test_settings: EndToEndTestSettings,
+    file_client: FileClient,
+    simple_pdf_file_path: str,
+    research_paper_path: str,
+    classification_rules: list[ClassifierRule],
+):
+    """Test classifying files by their IDs"""
+    # Upload test files first to get their IDs
+    pdf_file = await file_client.upload_file(simple_pdf_file_path)
+    research_paper_file = await file_client.upload_file(research_paper_path)
+
+    classify_client = ClassifyClient.from_api_key(
+        api_key=e2e_test_settings.LLAMA_CLOUD_API_KEY.get_secret_value(),
+        base_url=e2e_test_settings.LLAMA_CLOUD_BASE_URL,
+        project_id=pdf_file.project_id,
+        organization_id=e2e_test_settings.LLAMA_CLOUD_ORGANIZATION_ID,
+    )
+
+    # Classify the uploaded files
+    results = await classify_client.aclassify_file_ids(
+        rules=classification_rules, file_ids=[pdf_file.id, research_paper_file.id]
+    )
+
+    assert isinstance(results, ClassifyJobResults)
+    assert len(results.items) == 2
+
+    file_id_to_expected_type = {
+        pdf_file.id: "number",
+        research_paper_file.id: "research_paper",
+    }
+    # Verify each file got classified
+    for item in results.items:
+        expected_type = file_id_to_expected_type[item.file_id]
+        assert item.result.type == expected_type
+
+
 @parameterize_sync_and_async
 @pytest.mark.asyncio
 async def test_classify_file_path(
@@ -149,7 +188,7 @@ async def test_classify_file_path(
             rules=classification_rules, file_input_path=simple_pdf_file_path
         )
 
-    assert isinstance(results, ClassifyJobResults)
+    assert isinstance(results, ClassifyJobResultsWithFiles)
     assert len(results.items) == 1
 
     # Verify the file got classified
@@ -180,7 +219,7 @@ async def test_classify_file_paths(
             file_input_paths=[simple_pdf_file_path, research_paper_path],
         )
 
-    assert isinstance(results, ClassifyJobResults)
+    assert isinstance(results, ClassifyJobResultsWithFiles)
     assert len(results.items) == 2
 
     file_name_to_expected_type = {
@@ -189,8 +228,7 @@ async def test_classify_file_paths(
     }
     # Verify each file got classified
     for item in results.items:
-        file = await file_client.get_file(item.file_id)
-        expected_type = file_name_to_expected_type[file.name]
+        expected_type = file_name_to_expected_type[item.file.name]
         assert item.result.type == expected_type
 
 

ts/llama_cloud_services/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llama-cloud-services",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "type": "module",
   "license": "MIT",
   "scripts": {

ts/llama_cloud_services/src/beta/agent/client.ts

@@ -1,5 +1,5 @@
-import { createClient, createConfig } from "@hey-api/client-fetch";
-import { getEnv } from "@llamaindex/env";
+import { createClient } from "@hey-api/client-fetch";
+import { client as defaultClient } from "../../api";
 import {
   aggregateAgentDataApiV1BetaAgentDataAggregatePost,
   createAgentDataApiV1BetaAgentDataPost,
@@ -24,36 +24,19 @@ import type {
  */
 export class AgentClient<T = unknown> {
   private client: ReturnType<typeof createClient>;
-  private baseUrl: string;
-  private headers: Record<string, string>;
   private collection: string;
   private agentUrlId: string;
 
   constructor({
-    apiKey = getEnv("LLAMA_CLOUD_API_KEY"),
-    baseUrl = "https://api.cloud.llamaindex.ai/",
+    client = defaultClient,
     collection = "default",
     agentUrlId = "_public",
   }: {
-    apiKey?: string;
-    baseUrl?: string;
+    client?: ReturnType<typeof createClient>;
     collection?: string;
     agentUrlId?: string;
   }) {
-    this.baseUrl = baseUrl;
-
-    this.headers = {
-      "X-SDK-Name": "llamaindex-ts",
-      ...(apiKey && { Authorization: `Bearer ${apiKey}` }),
-    };
-
-    this.client = createClient(
-      createConfig({
-        baseUrl: this.baseUrl,
-        headers: this.headers,
-      }),
-    );
-
+    this.client = client;
     this.collection = collection;
     this.agentUrlId = agentUrlId;
   }
@@ -281,15 +264,13 @@ export interface AgentDataClientOptions {
  * @returns A new AgentClient instance
  */
 export function createAgentDataClient<T = unknown>({
-  apiKey,
-  baseUrl,
+  client = defaultClient,
   windowUrl,
   env,
   agentUrlId,
   collection = "default",
 }: {
-  apiKey?: string;
-  baseUrl?: string;
+  client?: ReturnType<typeof createClient>;
   windowUrl?: string;
   env?: Record<string, string>;
   agentUrlId?: string;
@@ -321,9 +302,8 @@ export function createAgentDataClient<T = unknown>({
   }
 
   return new AgentClient({
-    ...(apiKey && { apiKey }),
-    ...(baseUrl && { baseUrl }),
     ...(agentUrlId && { agentUrlId }),
     collection,
+    client,
   });
 }

ts/llama_cloud_services/tests/client.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { listProjectsApiV1ProjectsGet, client } from "../src/api.js";
+
+describe("Global client configuration", () => {
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it("adds X-SDK-Name header from global client config", async () => {
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockImplementation(async (input, init) => {
+        // Validate the header is present on the outgoing request
+        let headers: Headers;
+        if (input && typeof input === "object" && "headers" in (input as any)) {
+          headers = (input as Request).headers;
+        } else {
+          headers = new Headers((init && init.headers) || {});
+        }
+        expect(headers.get("X-SDK-Name")).toBe("llamaindex-ts");
+
+        return new Response(JSON.stringify([]), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        });
+      });
+
+    // Trigger any request via the generated SDK (imported through src/api.ts)
+    await listProjectsApiV1ProjectsGet({ throwOnError: false });
+
+    expect(fetchSpy).toHaveBeenCalledOnce();
+  });
+
+  it("respects additional custom headers set via setConfig", async () => {
+    const prevConfig = client.getConfig();
+    try {
+      client.setConfig({
+        ...prevConfig,
+        headers: {
+          ...(prevConfig.headers || {}),
+          "X-Custom-Header": "custom-value",
+        },
+      });
+
+      const fetchSpy = vi
+        .spyOn(globalThis, "fetch")
+        .mockImplementation(async (input, init) => {
+          let headers: Headers;
+          if (
+            input &&
+            typeof input === "object" &&
+            "headers" in (input as any)
+          ) {
+            headers = (input as Request).headers;
+          } else {
+            headers = new Headers((init && init.headers) || {});
+          }
+          expect(headers.get("X-SDK-Name")).toBe("llamaindex-ts");
+          expect(headers.get("X-Custom-Header")).toBe("custom-value");
+
+          return new Response(JSON.stringify([]), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          });
+        });
+
+      await listProjectsApiV1ProjectsGet({ throwOnError: false });
+      expect(fetchSpy).toHaveBeenCalledOnce();
+    } finally {
+      // Restore original configuration to avoid test cross-talk
+      client.setConfig(prevConfig);
+    }
+  });
+});