Compare commits

..

1 Commits

Author SHA1 Message Date
Logan Markewich c016f6ac4e update contributing instructions 2025-07-07 16:54:53 -06:00
34 changed files with 911 additions and 1147 deletions
-5
View File
@@ -1,5 +0,0 @@
---
"@llamaindex/cloud": patch
---
feat: init agent api on cloud sdk
-5
View File
@@ -1,5 +0,0 @@
---
"@llamaindex/cloud": patch
---
feat: init agent api on cloud sdk
-5
View File
@@ -1,5 +0,0 @@
---
"@llamaindex/core": patch
---
Fix createMemory factory when parsing options
+1 -3
View File
@@ -143,7 +143,7 @@ Before sending a PR, make sure of the following:
3. If you have a new feature, add a new example in the `examples` folder.
4. You have a descriptive changeset for each PR:
### Bumping the versions of packages you've modified
### Changesets
We use [changesets](https://github.com/changesets/changesets) for managing versions and changelogs. To create a new
changeset, run in the root folder:
@@ -152,8 +152,6 @@ changeset, run in the root folder:
pnpm changeset
```
You will be prompted to choose what packages need their versions bumped, and what kind of bump (major, minor or patch) is needed. Once you carry out this operation, the bumping will be automatic after the PR is merged.
## Publishing (maintainers only)
The [Release Github Action](.github/workflows/release.yml) is automatically generating and updating a
+3 -3
View File
@@ -35,7 +35,7 @@
"@radix-ui/react-tooltip": "^1.1.4",
"@scalar/api-client-react": "^1.1.25",
"@vercel/functions": "^1.5.0",
"ai": "^4.3.17",
"ai": "^3.4.33",
"class-variance-authority": "^0.7.0",
"clsx": "2.1.1",
"foxact": "^0.2.41",
@@ -70,7 +70,7 @@
"twoslash": "^0.3.1",
"use-stick-to-bottom": "^1.0.42",
"web-tree-sitter": "^0.24.4",
"zod": "^3.25.76"
"zod": "^3.25.67"
},
"devDependencies": {
"@next/env": "^15.3.0",
@@ -94,6 +94,6 @@
"typedoc": "0.28.3",
"typedoc-plugin-markdown": "^4.6.2",
"typedoc-plugin-merge-modules": " ^7.0.0",
"typescript": "^5.8.3"
"typescript": "^5.7.3"
}
}
+1 -1
View File
@@ -11,7 +11,7 @@
},
"devDependencies": {
"@cloudflare/workers-types": "^4.20241112.0",
"typescript": "^5.8.3",
"typescript": "^5.7.3",
"wrangler": "^3.89.0"
},
"dependencies": {
@@ -16,7 +16,7 @@
"@cloudflare/workers-types": "^4.20241112.0",
"@vitest/runner": "2.1.5",
"@vitest/snapshot": "2.1.5",
"typescript": "^5.8.3",
"typescript": "^5.7.3",
"vitest": "2.1.5",
"wrangler": "^3.87.0"
},
@@ -9,7 +9,7 @@
"preview": "vite preview"
},
"devDependencies": {
"typescript": "^5.8.3",
"typescript": "^5.7.3",
"vite": "^6.3.3",
"vite-plugin-wasm": "^3.4.1"
},
+2 -2
View File
@@ -8,7 +8,7 @@
"start": "next start"
},
"dependencies": {
"ai": "^4.3.17",
"ai": "^4.0.0",
"llamaindex": "workspace:*",
"next": "^15.3.3",
"react": "19.0.0",
@@ -20,6 +20,6 @@
"@types/react-dom": "^19.0.4",
"eslint": "9.16.0",
"eslint-config-next": "15.1.0",
"typescript": "^5.8.3"
"typescript": "^5.7.3"
}
}
@@ -17,6 +17,6 @@
"@types/node": "^22.9.0",
"@types/react": "^19.0.10",
"@types/react-dom": "^19.0.4",
"typescript": "^5.8.3"
"typescript": "^5.7.3"
}
}
@@ -21,6 +21,6 @@
"@types/react-dom": "^19.0.4",
"eslint": "9.16.0",
"eslint-config-next": "15.1.0",
"typescript": "^5.8.3"
"typescript": "^5.7.3"
}
}
@@ -15,7 +15,7 @@
"devDependencies": {
"@size-limit/preset-big-lib": "^11.1.6",
"size-limit": "^11.1.6",
"typescript": "^5.8.3",
"typescript": "^5.7.3",
"vite": "^6.3.3"
},
"dependencies": {
+1 -1
View File
@@ -22,6 +22,6 @@
"@types/react-dom": "19.0.4",
"rollup": "4.38.0",
"tailwindcss": "^4.1.4",
"typescript": "5.8.3"
"typescript": "5.7.3"
}
}
+1 -1
View File
@@ -27,6 +27,6 @@
"pg": "^8.12.0",
"pgvector": "0.2.0",
"tsx": "^4.19.3",
"zod": "^3.25.76"
"zod": "^3.25.67"
}
}
+3 -3
View File
@@ -60,7 +60,7 @@
"@notionhq/client": "^2.2.15",
"@pinecone-database/pinecone": "^4.0.0",
"@vercel/postgres": "^0.10.0",
"ai": "^4.3.17",
"ai": "^4.0.0",
"ajv": "^8.17.1",
"commander": "^12.1.0",
"dotenv": "^16.4.5",
@@ -69,12 +69,12 @@
"mongodb": "6.7.0",
"postgres": "^3.4.4",
"wikipedia": "^2.1.2",
"zod": "^3.25.76"
"zod": "^3.25.67"
},
"devDependencies": {
"@types/node": "^22.9.0",
"tsx": "^4.19.3",
"typescript": "^5.8.3"
"typescript": "^5.7.3"
},
"stackblitz": {
"startCommand": "npm start"
+2 -2
View File
@@ -21,13 +21,13 @@
},
"dependencies": {
"@llamaindex/cloud": "workspace:* || ^2.0.24",
"@llamaindex/excel": "workspace:*",
"@llamaindex/readers": "workspace:* || ^1.0.25",
"@llamaindex/excel": "workspace:*",
"llamaindex": "workspace:* || ^0.8.37"
},
"devDependencies": {
"@types/node": "^22.9.0",
"tsx": "^4.19.3",
"typescript": "^5.8.3"
"typescript": "^5.7.3"
}
}
+1 -1
View File
@@ -37,7 +37,7 @@
"prettier-plugin-organize-imports": "^4.1.0",
"prettier-plugin-tailwindcss": "^0.6.11",
"turbo": "^2.4.4",
"typescript": "^5.8.3",
"typescript": "^5.7.3",
"typescript-eslint": "^8.18.0",
"vitest": "^3.1.1"
},
+1 -1
View File
@@ -79,7 +79,7 @@
"next": "^15.3.3",
"rollup": "^4.28.1",
"tsx": "^4.19.3",
"typescript": "^5.8.3",
"typescript": "^5.7.3",
"vitest": "^2.1.5",
"webpack": "^5.97.1"
}
+1 -12
View File
@@ -15,17 +15,6 @@
],
"exports": {
"./openapi.json": "./openapi.json",
"./agent": {
"require": {
"types": "./agent/dist/index.d.cts",
"default": "./agent/dist/index.cjs"
},
"import": {
"types": "./agent/dist/index.d.ts",
"default": "./agent/dist/index.js"
},
"default": "./agent/dist/index.js"
},
"./api": {
"require": {
"types": "./api/dist/index.d.cts",
@@ -90,6 +79,6 @@
},
"dependencies": {
"p-retry": "^6.2.1",
"zod": "^3.25.76"
"zod": "^3.25.67"
}
}
-291
View File
@@ -1,291 +0,0 @@
import { createClient, createConfig } from "@hey-api/client-fetch";
import { getEnv } from "@llamaindex/env";
import pRetry from "p-retry";
import {
createAgentDataApiV1BetaAgentDataPost,
deleteAgentDataApiV1BetaAgentDataItemIdDelete,
getAgentDataApiV1BetaAgentDataItemIdGet,
searchAgentDataApiV1BetaAgentDataSearchPost,
updateAgentDataApiV1BetaAgentDataItemIdPut,
type AgentData,
} from "../client";
import type {
CreateAgentDataOptions,
ExtractedData,
ExtractOptions,
ListAgentDataOptions,
TypedAgentData,
TypedAgentDataItems,
UpdateAgentDataOptions,
} from "./types";
/**
* Async client for agent data operations
*/
export class AgentClient {
private client: ReturnType<typeof createClient>;
private baseUrl: string;
private headers: Record<string, string>;
constructor(options?: { apiKey?: string; baseUrl?: string }) {
const apiKey = options?.apiKey || getEnv("LLAMA_CLOUD_API_KEY");
this.baseUrl = options?.baseUrl || "https://api.cloud.llamaindex.ai/";
this.headers = {
"X-SDK-Name": "llamaindex-ts",
...(apiKey && { Authorization: `Bearer ${apiKey}` }),
};
this.client = createClient(
createConfig({
baseUrl: this.baseUrl,
headers: this.headers,
}),
);
}
/**
* Create new agent data
*/
async create<T = unknown>(
options: CreateAgentDataOptions<T>,
): Promise<TypedAgentData<T>> {
const response = await createAgentDataApiV1BetaAgentDataPost({
throwOnError: true,
body: {
agent_slug: options.agentSlug,
...(options.collection !== undefined && {
collection: options.collection,
}),
data: options.data as Record<string, unknown>,
},
client: this.client,
});
return this.transformResponse(response.data);
}
/**
* Get agent data by ID
*/
async get<T = unknown>(id: string): Promise<TypedAgentData<T> | null> {
try {
const response = await getAgentDataApiV1BetaAgentDataItemIdGet({
throwOnError: true,
path: { item_id: id },
client: this.client,
});
return this.transformResponse(response.data);
} catch (error) {
if (
error instanceof Error &&
"response" in error &&
(error as { response?: { status?: number } }).response?.status === 404
) {
return null;
}
throw error;
}
}
/**
* Update agent data
*/
async update<T = unknown>(
id: string,
options: UpdateAgentDataOptions<T>,
): Promise<TypedAgentData<T>> {
const response = await updateAgentDataApiV1BetaAgentDataItemIdPut({
throwOnError: true,
path: { item_id: id },
body: {
data: options.data as Record<string, unknown>,
},
client: this.client,
});
return this.transformResponse(response.data);
}
/**
* Delete agent data
*/
async delete(id: string): Promise<void> {
await deleteAgentDataApiV1BetaAgentDataItemIdDelete({
throwOnError: true,
path: { item_id: id },
client: this.client,
});
}
/**
* List agent data
*/
async list<T = unknown>(
options: ListAgentDataOptions,
): Promise<TypedAgentDataItems<T>> {
const response = await searchAgentDataApiV1BetaAgentDataSearchPost({
throwOnError: true,
body: {
agent_slug: options.agentSlug,
...(options.collection !== undefined && {
collection: options.collection,
}),
...(options.filter !== undefined && { filter: options.filter }),
...(options.orderBy !== undefined && { order_by: options.orderBy }),
...(options.pageSize !== undefined && { page_size: options.pageSize }),
...(options.pageToken !== undefined && {
page_token: options.pageToken,
}),
...(options.offset !== undefined && { offset: options.offset }),
},
client: this.client,
});
const result: TypedAgentDataItems<T> = {
items: response.data.items.map((item: AgentData) =>
this.transformResponse(item),
),
};
if (
response.data.total_size !== null &&
response.data.total_size !== undefined
) {
result.totalSize = response.data.total_size;
}
if (
response.data.next_page_token !== null &&
response.data.next_page_token !== undefined
) {
result.nextPageToken = response.data.next_page_token;
}
return result;
}
/**
* Extract data from agent with retry logic
*/
async extract<T = unknown>(
agentId: string,
input: unknown,
options?: ExtractOptions,
): Promise<ExtractedData<T>> {
const extractOptions = {
retries: options?.retryCount || 3,
onFailedAttempt: (error: {
attemptNumber: number;
retriesLeft: number;
}) => {
console.log(
`Extraction attempt ${error.attemptNumber} failed. ${error.retriesLeft} retries left.`,
);
},
minTimeout: options?.retryDelay || 1000,
maxTimeout: options?.timeout || 30000,
};
return pRetry(async () => {
// Note: The extract endpoint might not be in the generated client yet
// Using the native fetch API for this endpoint
const response = await fetch(
`${this.baseUrl}/api/v1/beta/agent-data/${agentId}/extract`,
{
method: "POST",
body: JSON.stringify({ input }),
headers: {
"Content-Type": "application/json",
...this.headers,
},
},
);
if (!response.ok) {
throw new Error(`Failed to extract data: ${response.statusText}`);
}
const extractedData = (await response.json()) as ExtractedData<T>;
// If status is still pending or in progress, poll for completion
if (
extractedData.status === "pending" ||
extractedData.status === "in_progress"
) {
return this.pollExtraction<T>(extractedData.id, options);
}
return extractedData;
}, extractOptions);
}
/**
* Poll for extraction completion
*/
private async pollExtraction<T = unknown>(
extractionId: string,
options?: ExtractOptions,
): Promise<ExtractedData<T>> {
const pollInterval = 2000; // 2 seconds
const maxAttempts = Math.floor((options?.timeout || 30000) / pollInterval);
for (let i = 0; i < maxAttempts; i++) {
await new Promise((resolve) => setTimeout(resolve, pollInterval));
const response = await fetch(
`${this.baseUrl}/api/v1/extractions/${extractionId}`,
{
headers: this.headers,
},
);
if (!response.ok) {
throw new Error(
`Failed to get extraction status: ${response.statusText}`,
);
}
const extractedData = (await response.json()) as ExtractedData<T>;
if (
extractedData.status === "completed" ||
extractedData.status === "failed"
) {
return extractedData;
}
}
throw new Error("Extraction timeout exceeded");
}
/**
* Transform API response to typed data
*/
private transformResponse<T = unknown>(data: AgentData): TypedAgentData<T> {
const result: TypedAgentData<T> = {
id: data.id!,
agentSlug: data.agent_slug,
data: data.data as T,
createdAt: new Date(data.created_at!),
updatedAt: new Date(data.updated_at!),
};
if (data.collection !== undefined) {
result.collection = data.collection;
}
return result;
}
}
/**
* Create a new AsyncAgentDataClient instance
*/
export function createAgentDataClient(options?: {
apiKey?: string;
baseUrl?: string;
}): AgentClient {
return new AgentClient(options);
}
-18
View File
@@ -1,18 +0,0 @@
export { AgentClient, createAgentDataClient } from "./client";
export type {
AgentDataT,
CreateAgentDataOptions,
ExtractOptions,
ExtractedData,
ExtractedT,
FilterOperation,
ListAgentDataOptions,
SortOptions,
StatusType,
TypedAgentData,
TypedAgentDataItems,
UpdateAgentDataOptions,
} from "./types";
export { StatusType as StatusTypeEnum } from "./types";
-98
View File
@@ -1,98 +0,0 @@
/**
* Status types for agent data processing
*/
export enum StatusType {
PENDING = "pending",
IN_PROGRESS = "in_progress",
COMPLETED = "completed",
FAILED = "failed",
}
/**
* Filter operation for searching/filtering agent data
*/
export interface FilterOperation {
[key: string]: unknown;
}
/**
* Base extracted data interface
*/
export interface ExtractedData<T = unknown> {
id: string;
status: StatusType;
data?: T;
error?: string;
createdAt: Date;
updatedAt: Date;
}
/**
* TypedAgentData interface for typed agent data
*/
export interface TypedAgentData<T = unknown> {
id: string;
agentSlug: string;
collection?: string;
data: T;
createdAt: Date;
updatedAt: Date;
}
/**
* Collection of typed agent data items
*/
export interface TypedAgentDataItems<T = unknown> {
items: TypedAgentData<T>[];
totalSize?: number;
nextPageToken?: string;
}
/**
* Options for creating agent data
*/
export interface CreateAgentDataOptions<T = unknown> {
agentSlug: string;
collection?: string;
data: T;
}
/**
* Options for updating agent data
*/
export interface UpdateAgentDataOptions<T = unknown> {
data: T;
}
/**
* Sort options for listing
*/
export interface SortOptions {
field: string;
order: "asc" | "desc";
}
/**
* Options for listing agent data
*/
export interface ListAgentDataOptions {
agentSlug: string;
collection?: string;
filter?: Record<string, FilterOperation>;
orderBy?: string;
pageSize?: number;
pageToken?: string;
offset?: number;
}
/**
* Options for extraction
*/
export interface ExtractOptions {
timeout?: number;
retryCount?: number;
retryDelay?: number;
}
export type ExtractedT<T> = T;
export type AgentDataT<T> = T;
-16
View File
@@ -7,21 +7,5 @@ client.setConfig({
},
});
export {
AgentClient,
createAgentDataClient,
StatusTypeEnum,
type AgentDataT,
type CreateAgentDataOptions,
type ExtractedData,
type ExtractedT,
type ExtractOptions,
type ListAgentDataOptions,
type SortOptions,
type StatusType,
type TypedAgentData,
type TypedAgentDataItems,
type UpdateAgentDataOptions,
} from "./agent";
export * from "./client";
export { client };
+1 -1
View File
@@ -312,7 +312,7 @@
"@llamaindex/env": "workspace:*",
"@types/node": "^22.9.0",
"magic-bytes.js": "^1.10.0",
"zod": "^3.25.76",
"zod": "^3.25.67",
"zod-to-json-schema": "^3.24.6"
}
}
+1 -12
View File
@@ -79,18 +79,7 @@ export function createMemory<TMessageOptions extends object = object>(
}
}
}
// Determine the correct options to pass to Memory
const resolvedOptions: MemoryOptions<TMessageOptions> = Array.isArray(
messagesOrOptions,
)
? options
: (messagesOrOptions as MemoryOptions<TMessageOptions>);
return new Memory<Record<string, never>, TMessageOptions>(
messages,
resolvedOptions,
);
return new Memory<Record<string, never>, TMessageOptions>(messages, options);
}
/**
+1 -44
View File
@@ -1,6 +1,6 @@
import { Settings } from "@llamaindex/core/global";
import type { ChatMessage, LLM } from "@llamaindex/core/llms";
import { createMemory, Memory, staticBlock } from "@llamaindex/core/memory";
import { createMemory, Memory } from "@llamaindex/core/memory";
import { MockLLM } from "@llamaindex/core/utils";
import type { Tokenizer } from "@llamaindex/env/tokenizers";
import {
@@ -392,47 +392,4 @@ describe("Memory", () => {
expect(messages[0]?.role).toBe("user"); // data role should be mapped to user
});
});
describe("memoryBlocks initialization", () => {
test("should include static block content in getLLM result", async () => {
const STATIC_CONTENT = "You are speaking with a helpful assistant.";
const block = staticBlock({
content: STATIC_CONTENT,
messageRole: "system",
});
const memoryWithBlock = createMemory({ memoryBlocks: [block] });
// Fetch messages via getLLM static block (priority 0) should always be present
const messages = await memoryWithBlock.getLLM();
// There should be exactly one message (the static block) when no other messages are added
expect(messages).toHaveLength(1);
expect(messages[0]?.content).toBe(STATIC_CONTENT);
expect(messages[0]?.role).toBe("system");
});
test("should retain static block alongside dynamic messages", async () => {
const STATIC_CONTENT = "Always respond in pirate speak.";
const block = staticBlock({
content: STATIC_CONTENT,
messageRole: "system",
});
const memoryWithBlock = createMemory({ memoryBlocks: [block] });
// Add a regular user message
await memoryWithBlock.add({ role: "user", content: "Hello there!" });
const messages = await memoryWithBlock.getLLM();
// Static block + user message
expect(messages).toHaveLength(2);
const contents = messages.map((m) => m.content);
expect(contents).toEqual(
expect.arrayContaining([STATIC_CONTENT, "Hello there!"]),
);
});
});
});
+1 -1
View File
@@ -33,7 +33,7 @@
"devDependencies": {
"@llamaindex/core": "workspace:*",
"@llamaindex/env": "workspace:*",
"zod": "^3.25.76"
"zod": "^3.25.67"
},
"peerDependencies": {
"@llamaindex/core": "workspace:*",
+3 -4
View File
@@ -39,12 +39,11 @@
"test": "vitest run"
},
"devDependencies": {
"@llamaindex/core": "workspace:*",
"ai": "^4.3.17",
"vitest": "^2.1.5"
"vitest": "^2.1.5",
"@llamaindex/core": "workspace:*"
},
"dependencies": {
"zod": "^3.25.76"
"zod": "^3.25.67"
},
"peerDependencies": {
"@llamaindex/core": "workspace:*",
+3 -3
View File
@@ -1,7 +1,7 @@
import { Settings } from "@llamaindex/core/global";
import type { BaseQueryEngine } from "@llamaindex/core/query-engine";
import { EngineResponse } from "@llamaindex/core/schema";
import { type LanguageModelV1, type Tool, tool } from "ai";
import { type CoreTool, type LanguageModelV1, tool } from "ai";
import { z } from "zod";
import { VercelLLM } from "./llm";
@@ -23,9 +23,9 @@ export function llamaindex({
options?: {
fields?: ResponseField[];
};
}): Tool {
}): CoreTool {
const llm = new VercelLLM({ model });
return Settings.withLLM<Tool>(llm, () => {
return Settings.withLLM<CoreTool>(llm, () => {
const queryEngine = index.asQueryEngine();
return tool({
description: description ?? "Get information about your documents.",
+5 -5
View File
@@ -32,13 +32,13 @@
"test:watch": "vitest watch"
},
"devDependencies": {
"@llamaindex/core": "workspace:*",
"@llamaindex/env": "workspace:*",
"@modelcontextprotocol/server-filesystem": "^2025.7.1",
"@types/node": "^22.9.0",
"@types/papaparse": "^5.3.15",
"ajv": "^8.12.0",
"vitest": "^2.1.5"
"vitest": "^2.1.5",
"@llamaindex/core": "workspace:*",
"@llamaindex/env": "workspace:*",
"ajv": "^8.12.0"
},
"peerDependencies": {
"@llamaindex/core": "workspace:*",
@@ -54,6 +54,6 @@
"marked": "^14.1.2",
"papaparse": "^5.4.1",
"wikipedia": "^2.1.2",
"zod": "^3.25.76"
"zod": "^3.25.67"
}
}
+1 -1
View File
@@ -11,7 +11,7 @@
"@swc/cli": "^0.5.0",
"@swc/core": "^1.9.2",
"assemblyscript": "^0.27.31",
"typescript": "^5.8.3"
"typescript": "^5.7.3"
},
"engines": {
"node": ">=20.0.0"
+869 -599
View File
File diff suppressed because it is too large Load Diff
+3 -3
View File
@@ -16,10 +16,10 @@
"test:node": "pnpm run build:node && node --test dist/node/index.e2e.js"
},
"devDependencies": {
"@llamaindex/openai": "workspace:*",
"@llamaindex/workflow": "workspace:*",
"@types/node": "^22.9.0",
"llamaindex": "workspace:*",
"zod": "^3.25.76"
"@llamaindex/workflow": "workspace:*",
"@llamaindex/openai": "workspace:*",
"zod": "^3.25.67"
}
}
+1 -1
View File
@@ -27,6 +27,6 @@
"tree-sitter": "^0.22.1",
"tree-sitter-javascript": "^0.23.1",
"tree-sitter-typescript": "^0.23.2",
"zod": "^3.25.76"
"zod": "^3.25.67"
}
}