psadk 1.3.7 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 1.4.0 (2026-05-18)
+
+### Features
+
+- **Prompt Caching Support**: Reduce costs and latency by up to 90% with built-in prompt caching
+  - New `enable_prompt_caching` parameter in `llm_config` for both PSAI and PSAgent ([#prompt-caching](https://pscode.lioncloud.net///commit/prompt-caching))
+  - New `cache_system_prompt` parameter to control system message caching
+  - New `cache_breakpoints` parameter for advanced cache control in agents
+  - Works with all LLM providers (OpenAI, Anthropic, Google Gemini, AWS Bedrock, Azure OpenAI)
+  - Automatic cache management through the LLM Gateway
+  - See `docs/PROMPT_CACHING.md` for comprehensive guide and examples
+  - Updated `PSAI.llm()` and `PSAI.llmStream()` to support prompt caching parameters
+  - Enhanced `PSAgentConfig` interface with caching configuration options
+  - Improved message formatting to support Anthropic-style cache_control blocks
+
+### Documentation
+
+- Add comprehensive prompt caching guide ([docs/PROMPT_CACHING.md](docs/PROMPT_CACHING.md))
+- Add prompt caching examples ([examples/prompt-caching-example.ts](examples/prompt-caching-example.ts))
+- Update README with feature highlights and caching documentation link
+
+### Non-Breaking Changes
+
+- All caching features are opt-in via configuration
+- Existing code continues to work without modification
+- Default behavior unchanged (caching disabled by default)
+
+## 1.3.8 (2026-05-15)
+
+### Features
+
+- **agent-core**: Add new agent-core module for low-level agent runtime
+  - Stateful agent wrapper with lifecycle management
+  - Event-driven execution loop with tool calling
+  - LLM proxy for server-side routing
+  - Built on @mariozechner/pi-ai library
+  - Import via `psadk/agent-core` subpath export
+- **appToken**: Add support for app-level authentication tokens
+  - All API methods now support optional `X-App-Authorization` header
+  - Pass `appToken` parameter to PSAI constructor
+
+### Dependencies
+
+- Add @mariozechner/pi-ai (^0.73.0)
+- Add typebox (^1.1.38) for runtime type validation
+- Add undici-types dev dependency
+
+### Build
+
+- Update TypeScript configuration to support DOM types for HeadersInit
+- Add skipLibCheck to resolve dependency type issues
+
 ## 1.1.0 (2025-09-17)
 
 ### Features

package/README.md

@@ -10,10 +10,160 @@ ps adk adapter
 $ npm install psadk
 ```
 
+## Features
+
+- **Multi-Provider LLM Support**: OpenAI, Anthropic, Google Gemini, AWS Bedrock, Azure OpenAI, and more
+- **A2A Protocol Compatible**: Build agents that work with the Agent-to-Agent protocol
+- **Prompt Caching**: Reduce costs and latency with built-in prompt caching support (90% cost reduction!)
+- **Custom Tools**: Create and integrate custom tools with your agents
+- **Type-Safe**: Full TypeScript support with comprehensive type definitions
+- **Authentication**: Built-in JWT authentication and token management
+
 ## Documentation
 
 The classes are documented here [Documentation](./globals.md)
 
+**New:** [Prompt Caching Guide](./docs/PROMPT_CACHING.md) - Learn how to reduce costs and latency by 90% with prompt caching
+
+## Agent Core Module
+
+The `agent-core` module provides a low-level, event-driven agent runtime built on `@earendil-works/pi-ai`. This module is designed for advanced use cases where you need fine-grained control over agent execution, tool calling, and message handling.
+
+> **Note**: The `agent-core` module adds additional dependencies including LLM provider SDKs. It's imported separately via `psadk/agent-core` to keep the main package lightweight.
+
+### Installation
+
+```typescript
+import { Agent } from 'psadk/agent-core';
+```
+
+### Key Features
+
+- **Stateful Agent Execution**: Lifecycle management with states (idle, running, stopped, error)
+- **Event-Driven Architecture**: Hooks for messages, thinking, tool calls, and errors
+- **Tool Execution**: Sequential and parallel tool calling modes
+- **Message History**: Automatic tracking and state management
+- **LLM Proxy**: Server-side routing for LLM calls
+- **Type Safety**: Comprehensive TypeScript types with runtime validation using TypeBox
+
+### Basic Example
+
+```typescript
+import { Agent } from 'psadk/agent-core';
+
+const agent = new Agent({
+  name: 'MyAgent',
+  model: 'gpt-4',
+  systemPrompt: 'You are a helpful assistant.',
+  tools: [
+    {
+      name: 'get_weather',
+      description: 'Get the current weather for a location',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          location: { type: 'string' },
+        },
+        required: ['location'],
+      },
+      execute: async ({ location }) => {
+        // Implementation
+        return { temperature: 72, conditions: 'sunny' };
+      },
+    },
+  ],
+  onMessage: (msg) => console.log('Agent:', msg.content),
+  onThinking: (thinking) => console.log('Thinking:', thinking),
+  onToolCall: (toolCall) => console.log('Tool:', toolCall.name),
+  onError: (error) => console.error('Error:', error),
+});
+
+// Start the agent and send a message
+await agent.run("What's the weather in San Francisco?");
+```
+
+### Agent Configuration
+
+```typescript
+interface AgentConfig {
+  name: string;
+  model: string;
+  systemPrompt?: string;
+  tools?: Tool[];
+  parallel?: boolean; // Enable parallel tool execution
+  maxSteps?: number; // Maximum number of execution steps
+  onMessage?: (message: Message) => void;
+  onThinking?: (thinking: string) => void;
+  onToolCall?: (toolCall: ToolCall) => void;
+  onToolResult?: (result: ToolResult) => void;
+  onError?: (error: Error) => void;
+  onStateChange?: (state: AgentState) => void;
+}
+```
+
+### Advanced: Using the Proxy
+
+The proxy module allows you to route LLM calls through a server:
+
+```typescript
+import { ProxyStream } from 'psadk/agent-core';
+
+const proxy = new ProxyStream({
+  endpoint: 'https://your-server.com/llm',
+  apiKey: 'your-api-key',
+});
+
+const stream = await proxy.createCompletion({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+### Agent Lifecycle
+
+The agent follows a state machine:
+
+1. **idle**: Initial state, ready to accept tasks
+2. **running**: Actively processing a task
+3. **stopped**: Gracefully stopped
+4. **error**: Encountered an error
+
+```typescript
+agent.onStateChange((state) => {
+  console.log(`Agent state changed to: ${state}`);
+});
+
+// Stop the agent
+await agent.stop();
+
+// Reset to idle state
+await agent.reset();
+```
+
+### Error Handling
+
+```typescript
+const agent = new Agent({
+  name: 'SafeAgent',
+  model: 'gpt-4',
+  onError: (error) => {
+    console.error('Agent error:', error.message);
+    // Handle error (e.g., retry, alert, log)
+  },
+});
+
+try {
+  await agent.run('Process this task');
+} catch (error) {
+  // Errors are also thrown, so you can handle them here
+  console.error('Task failed:', error);
+}
+```
+
 ## Developing with PSADK
 
 ### A2A Server

package/build/main/lib/PSAI.d.ts

@@ -11,12 +11,16 @@ export declare class PSAI {
     embedQuery(text: string, embeddingModel?: string): Promise<number[]>;
     embedDocuments(text: string[], embeddingModel?: string): Promise<number[][]>;
     getModels(): Promise<any>;
+    private prepareMessages;
+    private buildRequest;
     llm(prompt: string, model?: string, systemmsg?: string, llm_config?: {
         presence_penalty?: number;
         frequency_penalty?: number;
         max_tokens?: number;
         temperature?: number;
         top_p?: number;
+        enable_prompt_caching?: boolean;
+        cache_system_prompt?: boolean;
     } & Record<string, any>): Promise<any>;
     llmStream(prompt: string, model?: string, systemmsg?: string, llm_config?: {
         presence_penalty?: number;
@@ -24,6 +28,8 @@ export declare class PSAI {
         max_tokens?: number;
         temperature?: number;
         top_p?: number;
+        enable_prompt_caching?: boolean;
+        cache_system_prompt?: boolean;
     } & Record<string, any>): Promise<any>;
     static getServiceToken(options?: Record<string, string>): Promise<string>;
     /**