@acontext/acontext 0.0.1 → 0.0.2

package/README.md

@@ -1,4 +1,4 @@
-# acontext client for TypeScript
+# Acontext client for TypeScript
 
 TypeScript SDK for interacting with the Acontext REST API.
 
@@ -13,7 +13,7 @@ npm install @acontext/acontext
 ```typescript
 import { AcontextClient, MessagePart } from '@acontext/acontext';
 
-const client = new AcontextClient({ apiKey: 'sk_project_token' });
+const client = new AcontextClient({ apiKey: 'sk-ac-your-root-api-bearer-token' });
 
 // List spaces for the authenticated project
 const spaces = await client.spaces.list();
@@ -30,6 +30,9 @@ await client.sessions.sendMessage(
   },
   { format: 'acontext' }
 );
+
+// Flush session buffer when needed
+await client.sessions.flush(session.id);
 ```
 
 See the inline documentation for the full list of helpers covering sessions, spaces, disks, and artifact uploads.
@@ -41,7 +44,7 @@ Artifacts now live under project disks. Create a disk first, then upload files t
 ```typescript
 import { AcontextClient, FileUpload } from '@acontext/acontext';
 
-const client = new AcontextClient({ apiKey: 'sk_project_token' });
+const client = new AcontextClient({ apiKey: 'sk-ac-your-root-api-bearer-token' });
 
 const disk = await client.disks.create();
 await client.disks.artifacts.upsert(
@@ -63,7 +66,7 @@ await client.disks.artifacts.upsert(
 ```typescript
 import { AcontextClient } from '@acontext/acontext';
 
-const client = new AcontextClient({ apiKey: 'sk_project_token' });
+const client = new AcontextClient({ apiKey: 'sk-ac-your-root-api-bearer-token' });
 
 const space = await client.spaces.create();
 const page = await client.blocks.create(space.id, {
@@ -78,3 +81,116 @@ await client.blocks.create(space.id, {
 });
 ```
 
+## Managing sessions
+
+### Flush session buffer
+
+The `flush` method clears the session buffer, useful for managing session state:
+
+```typescript
+const result = await client.sessions.flush('session-uuid');
+console.log(result); // { status: 0, errmsg: '' }
+```
+
+## Working with tools
+
+The SDK provides APIs to manage tool names within your project:
+
+### Get tool names
+
+```typescript
+const tools = await client.tools.getToolName();
+for (const tool of tools) {
+  console.log(`${tool.name} (used in ${tool.sop_count} SOPs)`);
+}
+```
+
+### Rename tool names
+
+```typescript
+const result = await client.tools.renameToolName({
+  rename: [
+    { oldName: 'calculate', newName: 'calculate_math' },
+    { oldName: 'search', newName: 'search_web' },
+  ],
+});
+console.log(result); // { status: 0, errmsg: '' }
+```
+
+## Semantic search within spaces
+
+The SDK provides three powerful semantic search APIs for finding content within your spaces:
+
+### 1. Experience Search (Advanced AI-powered search)
+
+The most sophisticated search that can operate in two modes: **fast** (quick semantic search) or **agentic** (AI-powered iterative refinement).
+
+```typescript
+import { AcontextClient } from '@acontext/acontext';
+
+const client = new AcontextClient({ apiKey: 'sk_project_token' });
+
+// Fast mode - quick semantic search
+const result = await client.spaces.experienceSearch('space-uuid', {
+  query: 'How to implement authentication?',
+  limit: 10,
+  mode: 'fast',
+  semanticThreshold: 0.8,
+});
+
+// Agentic mode - AI-powered iterative search
+const agenticResult = await client.spaces.experienceSearch('space-uuid', {
+  query: 'What are the best practices for API security?',
+  limit: 10,
+  mode: 'agentic',
+  maxIterations: 20,
+});
+
+// Access results
+for (const block of result.cited_blocks) {
+  console.log(`${block.title} (distance: ${block.distance})`);
+}
+
+if (result.final_answer) {
+  console.log(`AI Answer: ${result.final_answer}`);
+}
+```
+
+### 2. Semantic Global (Search page/folder titles)
+
+Search for pages and folders by their titles using semantic similarity (like a semantic version of `glob`):
+
+```typescript
+// Find pages about authentication
+const results = await client.spaces.semanticGlobal('space-uuid', {
+  query: 'authentication and authorization pages',
+  limit: 10,
+  threshold: 1.0, // Only show results with distance < 1.0
+});
+
+for (const block of results) {
+  console.log(`${block.title} - ${block.type}`);
+}
+```
+
+### 3. Semantic Grep (Search content blocks)
+
+Search through actual content blocks using semantic similarity (like a semantic version of `grep`):
+
+```typescript
+// Find code examples for JWT validation
+const results = await client.spaces.semanticGrep('space-uuid', {
+  query: 'JWT token validation code examples',
+  limit: 15,
+  threshold: 0.7,
+});
+
+for (const block of results) {
+  console.log(`${block.title} - distance: ${block.distance}`);
+  const content = block.props.text || block.props.content;
+  if (content) {
+    console.log(`Content: ${String(content).substring(0, 100)}...`);
+  }
+}
+```
+

package/dist/client.d.ts

@@ -5,6 +5,7 @@ import { BlocksAPI } from './resources/blocks';
 import { DisksAPI } from './resources/disks';
 import { SessionsAPI } from './resources/sessions';
 import { SpacesAPI } from './resources/spaces';
+import { ToolsAPI } from './resources/tools';
 import { RequesterProtocol } from './client-types';
 export interface AcontextClientOptions {
     apiKey?: string | null;
@@ -22,6 +23,7 @@ export declare class AcontextClient implements RequesterProtocol {
     disks: DisksAPI;
     artifacts: DisksAPI['artifacts'];
     blocks: BlocksAPI;
+    tools: ToolsAPI;
     constructor(options?: AcontextClientOptions);
     get baseUrl(): string;
     request<T = unknown>(method: string, path: string, options?: {

package/dist/client.js

@@ -42,6 +42,7 @@ const blocks_1 = require("./resources/blocks");
 const disks_1 = require("./resources/disks");
 const sessions_1 = require("./resources/sessions");
 const spaces_1 = require("./resources/spaces");
+const tools_1 = require("./resources/tools");
 const constants_1 = require("./constants");
 class AcontextClient {
     constructor(options = {}) {
@@ -75,6 +76,7 @@ class AcontextClient {
         this.disks = new disks_1.DisksAPI(this);
         this.artifacts = this.disks.artifacts;
         this.blocks = new blocks_1.BlocksAPI(this);
+        this.tools = new tools_1.ToolsAPI(this);
     }
     get baseUrl() {
         return this._baseUrl;

package/dist/resources/blocks.d.ts

@@ -3,6 +3,7 @@
  */
 import { RequesterProtocol } from '../client-types';
 import { Block } from '../types';
+import { InsertBlockResponse } from '../types/tool';
 export declare class BlocksAPI {
     private requester;
     constructor(requester: RequesterProtocol);
@@ -15,7 +16,7 @@ export declare class BlocksAPI {
         parentId?: string | null;
         title?: string | null;
         props?: Record<string, unknown> | null;
-    }): Promise<Block>;
+    }): Promise<InsertBlockResponse>;
     delete(spaceId: string, blockId: string): Promise<void>;
     getProperties(spaceId: string, blockId: string): Promise<Block>;
     updateProperties(spaceId: string, blockId: string, options: {

package/dist/resources/blocks.js

@@ -5,6 +5,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BlocksAPI = void 0;
 const types_1 = require("../types");
+const tool_1 = require("../types/tool");
 class BlocksAPI {
     constructor(requester) {
         this.requester = requester;
@@ -36,7 +37,7 @@ class BlocksAPI {
         const data = await this.requester.request('POST', `/space/${spaceId}/block`, {
             jsonData: payload,
         });
-        return types_1.BlockSchema.parse(data);
+        return tool_1.InsertBlockResponseSchema.parse(data);
     }
     async delete(spaceId, blockId) {
         await this.requester.request('DELETE', `/space/${spaceId}/block/${blockId}`);

package/dist/resources/index.d.ts

@@ -5,3 +5,4 @@ export * from './spaces';
 export * from './sessions';
 export * from './disks';
 export * from './blocks';
+export * from './tools';

package/dist/resources/index.js

@@ -21,3 +21,4 @@ __exportStar(require("./spaces"), exports);
 __exportStar(require("./sessions"), exports);
 __exportStar(require("./disks"), exports);
 __exportStar(require("./blocks"), exports);
+__exportStar(require("./tools"), exports);

package/dist/resources/sessions.d.ts

@@ -45,4 +45,8 @@ export declare class SessionsAPI {
         format?: 'acontext' | 'openai' | 'anthropic';
         timeDesc?: boolean | null;
     }): Promise<GetMessagesOutput>;
+    flush(sessionId: string): Promise<{
+        status: number;
+        errmsg: string;
+    }>;
 }

package/dist/resources/sessions.js

@@ -131,5 +131,9 @@ class SessionsAPI {
         });
         return types_1.GetMessagesOutputSchema.parse(data);
     }
+    async flush(sessionId) {
+        const data = await this.requester.request('POST', `/session/${sessionId}/flush`);
+        return data;
+    }
 }
 exports.SessionsAPI = SessionsAPI;

package/dist/resources/spaces.d.ts

@@ -2,7 +2,7 @@
  * Spaces endpoints.
  */
 import { RequesterProtocol } from '../client-types';
-import { ListSpacesOutput, Space } from '../types';
+import { ListSpacesOutput, SearchResultBlockItem, Space, SpaceSearchResult } from '../types';
 export declare class SpacesAPI {
     private requester;
     constructor(requester: RequesterProtocol);
@@ -19,4 +19,52 @@ export declare class SpacesAPI {
         configs: Record<string, unknown>;
     }): Promise<void>;
     getConfigs(spaceId: string): Promise<Space>;
+    /**
+     * Perform experience search within a space.
+     *
+     * This is the most advanced search option that can operate in two modes:
+     * - fast: Quick semantic search (default)
+     * - agentic: Iterative search with AI-powered refinement
+     *
+     * @param spaceId - The UUID of the space
+     * @param options - Search options
+     * @returns SpaceSearchResult containing cited blocks and optional final answer
+     */
+    experienceSearch(spaceId: string, options: {
+        query: string;
+        limit?: number | null;
+        mode?: 'fast' | 'agentic' | null;
+        semanticThreshold?: number | null;
+        maxIterations?: number | null;
+    }): Promise<SpaceSearchResult>;
+    /**
+     * Perform semantic global (glob) search for page/folder titles.
+     *
+     * Searches specifically for page/folder titles using semantic similarity,
+     * similar to a semantic version of the glob command.
+     *
+     * @param spaceId - The UUID of the space
+     * @param options - Search options
+     * @returns List of SearchResultBlockItem objects matching the query
+     */
+    semanticGlobal(spaceId: string, options: {
+        query: string;
+        limit?: number | null;
+        threshold?: number | null;
+    }): Promise<SearchResultBlockItem[]>;
+    /**
+     * Perform semantic grep search for content blocks.
+     *
+     * Searches through content blocks (actual text content) using semantic similarity,
+     * similar to a semantic version of the grep command.
+     *
+     * @param spaceId - The UUID of the space
+     * @param options - Search options
+     * @returns List of SearchResultBlockItem objects matching the query
+     */
+    semanticGrep(spaceId: string, options: {
+        query: string;
+        limit?: number | null;
+        threshold?: number | null;
+    }): Promise<SearchResultBlockItem[]>;
 }

package/dist/resources/spaces.js

@@ -44,5 +44,65 @@ class SpacesAPI {
         const data = await this.requester.request('GET', `/space/${spaceId}/configs`);
         return types_1.SpaceSchema.parse(data);
     }
+    /**
+     * Perform experience search within a space.
+     *
+     * This is the most advanced search option that can operate in two modes:
+     * - fast: Quick semantic search (default)
+     * - agentic: Iterative search with AI-powered refinement
+     *
+     * @param spaceId - The UUID of the space
+     * @param options - Search options
+     * @returns SpaceSearchResult containing cited blocks and optional final answer
+     */
+    async experienceSearch(spaceId, options) {
+        const params = (0, utils_1.buildParams)({
+            query: options.query,
+            limit: options.limit ?? null,
+            mode: options.mode ?? null,
+            semantic_threshold: options.semanticThreshold ?? null,
+            max_iterations: options.maxIterations ?? null,
+        });
+        const data = await this.requester.request('GET', `/space/${spaceId}/experience_search`, { params: Object.keys(params).length > 0 ? params : undefined });
+        return types_1.SpaceSearchResultSchema.parse(data);
+    }
+    /**
+     * Perform semantic global (glob) search for page/folder titles.
+     *
+     * Searches specifically for page/folder titles using semantic similarity,
+     * similar to a semantic version of the glob command.
+     *
+     * @param spaceId - The UUID of the space
+     * @param options - Search options
+     * @returns List of SearchResultBlockItem objects matching the query
+     */
+    async semanticGlobal(spaceId, options) {
+        const params = (0, utils_1.buildParams)({
+            query: options.query,
+            limit: options.limit ?? null,
+            threshold: options.threshold ?? null,
+        });
+        const data = await this.requester.request('GET', `/space/${spaceId}/semantic_global`, { params: Object.keys(params).length > 0 ? params : undefined });
+        return data.map((item) => types_1.SearchResultBlockItemSchema.parse(item));
+    }
+    /**
+     * Perform semantic grep search for content blocks.
+     *
+     * Searches through content blocks (actual text content) using semantic similarity,
+     * similar to a semantic version of the grep command.
+     *
+     * @param spaceId - The UUID of the space
+     * @param options - Search options
+     * @returns List of SearchResultBlockItem objects matching the query
+     */
+    async semanticGrep(spaceId, options) {
+        const params = (0, utils_1.buildParams)({
+            query: options.query,
+            limit: options.limit ?? null,
+            threshold: options.threshold ?? null,
+        });
+        const data = await this.requester.request('GET', `/space/${spaceId}/semantic_grep`, { params: Object.keys(params).length > 0 ? params : undefined });
+        return data.map((item) => types_1.SearchResultBlockItemSchema.parse(item));
+    }
 }
 exports.SpacesAPI = SpacesAPI;

package/dist/resources/tools.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Tool endpoints.
+ */
+import { RequesterProtocol } from '../client-types';
+import { ToolRenameItem, ToolReferenceData, FlagResponse } from '../types/tool';
+export declare class ToolsAPI {
+    private requester;
+    constructor(requester: RequesterProtocol);
+    renameToolName(options: {
+        rename: ToolRenameItem[];
+    }): Promise<FlagResponse>;
+    getToolName(): Promise<ToolReferenceData[]>;
+}

package/dist/resources/tools.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Tool endpoints.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolsAPI = void 0;
+const tool_1 = require("../types/tool");
+class ToolsAPI {
+    constructor(requester) {
+        this.requester = requester;
+    }
+    async renameToolName(options) {
+        const payload = { rename: options.rename };
+        const data = await this.requester.request('PUT', '/tool/name', {
+            jsonData: payload,
+        });
+        return tool_1.FlagResponseSchema.parse(data);
+    }
+    async getToolName() {
+        const data = await this.requester.request('GET', '/tool/name');
+        return Array.isArray(data)
+            ? data.map((item) => tool_1.ToolReferenceDataSchema.parse(item))
+            : [];
+    }
+}
+exports.ToolsAPI = ToolsAPI;

package/dist/types/index.d.ts

@@ -5,3 +5,4 @@ export * from './space';
 export * from './session';
 export * from './disk';
 export * from './block';
+export * from './tool';

package/dist/types/index.js

@@ -21,3 +21,4 @@ __exportStar(require("./space"), exports);
 __exportStar(require("./session"), exports);
 __exportStar(require("./disk"), exports);
 __exportStar(require("./block"), exports);
+__exportStar(require("./tool"), exports);

package/dist/types/session.d.ts

@@ -56,7 +56,7 @@ export declare const SessionSchema: z.ZodObject<{
     id: z.ZodString;
     project_id: z.ZodString;
     space_id: z.ZodNullable<z.ZodString>;
-    configs: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    configs: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     created_at: z.ZodString;
     updated_at: z.ZodString;
 }, z.core.$strip>;
@@ -79,7 +79,7 @@ export declare const ListSessionsOutputSchema: z.ZodObject<{
         id: z.ZodString;
         project_id: z.ZodString;
         space_id: z.ZodNullable<z.ZodString>;
-        configs: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        configs: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         created_at: z.ZodString;
         updated_at: z.ZodString;
     }, z.core.$strip>>;

package/dist/types/session.js

@@ -36,7 +36,7 @@ exports.SessionSchema = zod_1.z.object({
     id: zod_1.z.string(),
     project_id: zod_1.z.string(),
     space_id: zod_1.z.string().nullable(),
-    configs: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+    configs: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable(),
     created_at: zod_1.z.string(),
     updated_at: zod_1.z.string(),
 });

package/dist/types/space.d.ts

@@ -5,7 +5,7 @@ import { z } from 'zod';
 export declare const SpaceSchema: z.ZodObject<{
     id: z.ZodString;
     project_id: z.ZodString;
-    configs: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    configs: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     created_at: z.ZodString;
     updated_at: z.ZodString;
 }, z.core.$strip>;
@@ -14,7 +14,7 @@ export declare const ListSpacesOutputSchema: z.ZodObject<{
     items: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         project_id: z.ZodString;
-        configs: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        configs: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         created_at: z.ZodString;
         updated_at: z.ZodString;
     }, z.core.$strip>>;
@@ -22,3 +22,22 @@ export declare const ListSpacesOutputSchema: z.ZodObject<{
     has_more: z.ZodBoolean;
 }, z.core.$strip>;
 export type ListSpacesOutput = z.infer<typeof ListSpacesOutputSchema>;
+export declare const SearchResultBlockItemSchema: z.ZodObject<{
+    block_id: z.ZodString;
+    title: z.ZodString;
+    type: z.ZodString;
+    props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    distance: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type SearchResultBlockItem = z.infer<typeof SearchResultBlockItemSchema>;
+export declare const SpaceSearchResultSchema: z.ZodObject<{
+    cited_blocks: z.ZodArray<z.ZodObject<{
+        block_id: z.ZodString;
+        title: z.ZodString;
+        type: z.ZodString;
+        props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        distance: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    final_answer: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type SpaceSearchResult = z.infer<typeof SpaceSearchResultSchema>;

package/dist/types/space.js

@@ -3,12 +3,12 @@
  * Type definitions for space resources.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ListSpacesOutputSchema = exports.SpaceSchema = void 0;
+exports.SpaceSearchResultSchema = exports.SearchResultBlockItemSchema = exports.ListSpacesOutputSchema = exports.SpaceSchema = void 0;
 const zod_1 = require("zod");
 exports.SpaceSchema = zod_1.z.object({
     id: zod_1.z.string(),
     project_id: zod_1.z.string(),
-    configs: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+    configs: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable(),
     created_at: zod_1.z.string(),
     updated_at: zod_1.z.string(),
 });
@@ -17,3 +17,14 @@ exports.ListSpacesOutputSchema = zod_1.z.object({
     next_cursor: zod_1.z.string().nullable().optional(),
     has_more: zod_1.z.boolean(),
 });
+exports.SearchResultBlockItemSchema = zod_1.z.object({
+    block_id: zod_1.z.string(),
+    title: zod_1.z.string(),
+    type: zod_1.z.string(),
+    props: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+    distance: zod_1.z.number().nullable(),
+});
+exports.SpaceSearchResultSchema = zod_1.z.object({
+    cited_blocks: zod_1.z.array(exports.SearchResultBlockItemSchema),
+    final_answer: zod_1.z.string().nullable(),
+});

package/dist/types/tool.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Type definitions for tool resources.
+ */
+import { z } from 'zod';
+export declare const ToolRenameItemSchema: z.ZodObject<{
+    oldName: z.ZodString;
+    newName: z.ZodString;
+}, z.core.$strip>;
+export type ToolRenameItem = z.infer<typeof ToolRenameItemSchema>;
+export declare const ToolReferenceDataSchema: z.ZodObject<{
+    name: z.ZodString;
+    sop_count: z.ZodNumber;
+}, z.core.$strip>;
+export type ToolReferenceData = z.infer<typeof ToolReferenceDataSchema>;
+export declare const FlagResponseSchema: z.ZodObject<{
+    status: z.ZodNumber;
+    errmsg: z.ZodString;
+}, z.core.$strip>;
+export type FlagResponse = z.infer<typeof FlagResponseSchema>;
+export declare const InsertBlockResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export type InsertBlockResponse = z.infer<typeof InsertBlockResponseSchema>;

package/dist/types/tool.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Type definitions for tool resources.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InsertBlockResponseSchema = exports.FlagResponseSchema = exports.ToolReferenceDataSchema = exports.ToolRenameItemSchema = void 0;
+const zod_1 = require("zod");
+exports.ToolRenameItemSchema = zod_1.z.object({
+    oldName: zod_1.z.string(),
+    newName: zod_1.z.string(),
+});
+exports.ToolReferenceDataSchema = zod_1.z.object({
+    name: zod_1.z.string(),
+    sop_count: zod_1.z.number(),
+});
+exports.FlagResponseSchema = zod_1.z.object({
+    status: zod_1.z.number(),
+    errmsg: zod_1.z.string(),
+});
+exports.InsertBlockResponseSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acontext/acontext",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "TypeScript SDK for the Acontext API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",