@alexkroman1/aai 1.6.1 → 1.7.0

package/sdk/providers/kv/s3.ts

@@ -0,0 +1,33 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * S3-compatible KV descriptor.
+ *
+ * Resolves to unstorage's `s3` driver — works with AWS S3, Tigris,
+ * Cloudflare R2, and other S3-protocol stores. Credentials are
+ * pulled from the agent env at session start (the descriptor stays
+ * secret-free).
+ *
+ * Required agent env: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`.
+ * Optional: `AWS_SESSION_TOKEN` (for temporary credentials).
+ */
+
+import type { KvProvider } from "../../providers.ts";
+
+export const S3_KV_KIND = "s3" as const;
+
+export interface S3KvOptions {
+  bucket: string;
+  /** Custom endpoint URL — required for non-AWS providers (Tigris, R2). */
+  endpoint?: string;
+  /** Region. Defaults to `"auto"`. */
+  region?: string;
+}
+
+export type S3KvProvider = KvProvider & {
+  readonly kind: typeof S3_KV_KIND;
+  readonly options: S3KvOptions;
+};
+
+export function s3Kv(opts: S3KvOptions): S3KvProvider {
+  return { kind: S3_KV_KIND, options: { ...opts } };
+}

package/sdk/providers/kv-barrel.ts

@@ -0,0 +1,19 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * `@alexkroman1/aai/kv` subpath barrel.
+ *
+ * Re-exports KV descriptor factories. Importing this barrel does
+ * not pull in any unstorage driver — the host resolver handles that
+ * at session start.
+ */
+
+export type { Kv } from "../kv.ts";
+export type { KvProvider } from "../providers.ts";
+// biome-ignore lint/performance/noReExportAll: subpath barrel
+export * from "./kv/fs.ts";
+// biome-ignore lint/performance/noReExportAll: subpath barrel
+export * from "./kv/memory.ts";
+// biome-ignore lint/performance/noReExportAll: subpath barrel
+export * from "./kv/redis.ts";
+// biome-ignore lint/performance/noReExportAll: subpath barrel
+export * from "./kv/s3.ts";

package/sdk/providers/vector/in-memory.ts

@@ -0,0 +1,23 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * In-memory Vector descriptor.
+ *
+ * Resolves to a process-local store with deterministic hash-based
+ * pseudo-embeddings. Quality is intentionally bad — the purpose is
+ * proving tool wiring during `aai dev`, not retrieval ranking.
+ */
+
+import type { VectorProvider } from "../../providers.ts";
+
+export const IN_MEMORY_VECTOR_KIND = "in-memory" as const;
+
+export type InMemoryVectorOptions = Record<string, never>;
+
+export type InMemoryVectorProvider = VectorProvider & {
+  readonly kind: typeof IN_MEMORY_VECTOR_KIND;
+  readonly options: InMemoryVectorOptions;
+};
+
+export function inMemoryVector(): InMemoryVectorProvider {
+  return { kind: IN_MEMORY_VECTOR_KIND, options: {} };
+}

package/sdk/providers/vector/pinecone.ts

@@ -0,0 +1,27 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Pinecone Vector descriptor.
+ *
+ * The descriptor flows through bundle → server → runtime without
+ * importing `@pinecone-database/pinecone`. The host-side resolver in
+ * `host/providers/resolve-vector.ts` constructs a real client during
+ * `createRuntime`, using `PINECONE_API_KEY` from the agent's env.
+ */
+
+import type { VectorProvider } from "../../providers.ts";
+
+export const PINECONE_VECTOR_KIND = "pinecone" as const;
+
+export interface PineconeOptions {
+  /** Pinecone index name. The index must be created with integrated-inference embed config. */
+  index: string;
+}
+
+export type PineconeProvider = VectorProvider & {
+  readonly kind: typeof PINECONE_VECTOR_KIND;
+  readonly options: PineconeOptions;
+};
+
+export function pinecone(opts: PineconeOptions): PineconeProvider {
+  return { kind: PINECONE_VECTOR_KIND, options: { ...opts } };
+}

package/sdk/providers/vector-barrel.ts

@@ -0,0 +1,15 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * `@alexkroman1/aai/vector` subpath barrel.
+ *
+ * Re-exports descriptor factories. Importing this barrel does not
+ * pull in `@pinecone-database/pinecone` — the host resolver handles
+ * that at session start.
+ */
+
+export type { VectorProvider } from "../providers.ts";
+export type { Vector, VectorMatch, VectorQueryOptions } from "../vector.ts";
+// biome-ignore lint/performance/noReExportAll: subpath barrel
+export * from "./vector/in-memory.ts";
+// biome-ignore lint/performance/noReExportAll: subpath barrel
+export * from "./vector/pinecone.ts";

package/sdk/providers.ts

@@ -48,6 +48,12 @@ export type LlmProvider = ProviderDescriptor<string, Record<string, unknown>>;
 /** Descriptor for a TTS provider. Returned by factories like `cartesia(...)`. */
 export type TtsProvider = ProviderDescriptor<string, Record<string, unknown>>;
 
+/** Descriptor for a KV backend. Returned by factories like `redisKv()`. */
+export type KvProvider = ProviderDescriptor<string, Record<string, unknown>>;
+
+/** Descriptor for a Vector backend. Returned by factories like `pinecone(...)`. */
+export type VectorProvider = ProviderDescriptor<string, Record<string, unknown>>;
+
 /**
  * Session mode derived from which provider triple is set.
  *

package/sdk/types.ts

@@ -5,7 +5,14 @@
 
 import { z } from "zod";
 import type { Kv } from "./kv.ts";
-import type { LlmProvider, SttProvider, TtsProvider } from "./providers.ts";
+import type {
+  KvProvider,
+  LlmProvider,
+  SttProvider,
+  TtsProvider,
+  VectorProvider,
+} from "./providers.ts";
+import type { Vector } from "./vector.ts";
 
 /**
  * Identifier for a built-in server-side tool.
@@ -80,6 +87,8 @@ export type ToolContext<S = Record<string, unknown>> = {
   state: S;
   /** Key-value store scoped to this agent deployment. */
   kv: Kv;
+  /** Vector store scoped to this agent deployment. */
+  vector: Vector;
   /** Read-only snapshot of conversation messages so far. */
   messages: readonly Message[];
   /** Unique identifier for the current session. Useful for correlating logs across concurrent sessions. */
@@ -233,6 +242,10 @@ export type AgentDef<S = Record<string, unknown>> = {
    * pipeline mode.
    */
   tts?: TtsProvider;
+  /** Pluggable KV backend. Falls back to platform default when omitted. */
+  kv?: KvProvider;
+  /** Pluggable Vector backend. Falls back to platform default when omitted. */
+  vector?: VectorProvider;
 };
 
 // ─── Zod schemas ────────────────────────────────────────────────────────────

package/sdk/vector.ts

@@ -0,0 +1,32 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Vector storage interface used by agents.
+ *
+ * Agents access the store via `ctx.vector`. Backends embed text on
+ * write and run similarity search on read; the interface is text-in,
+ * matches-out so users never deal with embedding vectors directly.
+ *
+ * @public
+ */
+export type VectorMatch = {
+  id: string;
+  score: number;
+  text: string;
+  metadata?: Record<string, unknown>;
+};
+
+/** @public */
+export type VectorQueryOptions = {
+  /** Number of results to return. Default 5, max 100. */
+  topK?: number;
+  /** Backend-specific filter (Pinecone uses MongoDB-like operators). */
+  filter?: Record<string, unknown>;
+};
+
+/** @public */
+export type Vector = {
+  upsert(id: string, text: string, metadata?: Record<string, unknown>): Promise<void>;
+  query(text: string, opts?: VectorQueryOptions): Promise<VectorMatch[]>;
+  delete(ids: string | string[]): Promise<void>;
+  close?(): void;
+};