@ai-sdk/angular 0.0.0-02dba89b-20251009204516

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2023 Vercel, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,643 @@
+# AI SDK Angular
+
+Angular UI components for the [AI SDK v5](https://ai-sdk.dev/docs).
+
+## Overview
+
+The `@ai-sdk/angular` package provides Angular-specific implementations using Angular signals for reactive state management:
+
+- **Chat** - Multi-turn conversations with streaming responses
+- **Completion** - Single-turn text generation
+- **StructuredObject** - Type-safe object generation with Zod schemas
+
+## Installation
+
+```bash
+npm install @ai-sdk/angular ai
+```
+
+### Peer Dependencies
+
+- Angular 16+ (`@angular/core`)
+- Zod v3+ (optional, for structured objects)
+
+## Chat
+
+Real-time conversation interface with streaming support.
+
+### Basic Usage
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
+import { Chat } from '@ai-sdk/angular';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-chat',
+  imports: [CommonModule, ReactiveFormsModule],
+  template: `
+    <div class="chat-container">
+      <div class="messages">
+        @for (message of chat.messages; track message.id) {
+          <div class="message" [ngClass]="message.role">
+            @for (part of message.parts; track $index) {
+              @switch (part.type) {
+                @case ('text') {
+                  <div style="white-space: pre-wrap">
+                    {{ part.text }}
+                    @if (part.state === 'streaming') {
+                      <span class="cursor">&#9646;</span>
+                    }
+                  </div>
+                }
+                @case ('reasoning') {
+                  <details>
+                    <summary>Reasoning</summary>
+                    <div style="white-space: pre-wrap; opacity: 80%">
+                      {{ part.text }}
+                    </div>
+                  </details>
+                }
+                @default {
+                  <code>{{ part | json }}</code>
+                }
+              }
+            }
+          </div>
+        }
+        @if (chat.status === 'submitted') {
+          <div><em>Waiting...</em></div>
+        }
+      </div>
+
+      <form [formGroup]="chatForm" (ngSubmit)="sendMessage()">
+        <input formControlName="userInput" placeholder="Type your message..." />
+        @if (chat.status === 'ready') {
+          <button type="submit" [disabled]="!chatForm.valid">Send</button>
+        } @else {
+          <button [disabled]="chat.status === 'error'" (click)="chat.stop()">
+            Stop
+          </button>
+        }
+      </form>
+    </div>
+  `,
+})
+export class ChatComponent {
+  private fb = inject(FormBuilder);
+
+  public chat = new Chat({});
+
+  chatForm = this.fb.group({
+    userInput: ['', Validators.required],
+  });
+
+  sendMessage() {
+    if (this.chatForm.invalid) return;
+
+    const userInput = this.chatForm.value.userInput;
+    this.chatForm.reset();
+
+    this.chat.sendMessage(
+      { text: userInput },
+      {
+        body: {
+          selectedModel: 'gpt-4o',
+        },
+      },
+    );
+  }
+}
+```
+
+### Constructor Options
+
+```typescript
+interface ChatInit<UI_MESSAGE extends UIMessage = UIMessage> {
+  /** Initial messages */
+  messages?: UI_MESSAGE[];
+
+  /** Custom ID generator */
+  generateId?: () => string;
+
+  /** Maximum conversation steps */
+  maxSteps?: number;
+
+  /** Tool call handler */
+  onToolCall?: (params: { toolCall: ToolCall }) => Promise<string>;
+
+  /** Completion callback */
+  onFinish?: (params: { message: UI_MESSAGE }) => void;
+
+  /** Error handler */
+  onError?: (error: Error) => void;
+
+  /** Custom transport */
+  transport?: ChatTransport;
+}
+```
+
+### Properties (Reactive)
+
+- `messages: UIMessage[]` - Array of conversation messages
+- `status: 'ready' | 'submitted' | 'streaming' | 'error'` - Current status
+- `error: Error | undefined` - Current error state
+
+### Methods
+
+```typescript
+// Send a message
+await chat.sendMessage(
+  message: UIMessageInput,
+  options?: {
+    body?: Record<string, any>;
+    headers?: Record<string, string>;
+  }
+);
+
+// Regenerate last assistant message
+await chat.regenerate(options?: {
+  body?: Record<string, any>;
+  headers?: Record<string, string>;
+});
+
+// Add tool execution result
+chat.addToolResult({
+  toolCallId: string;
+  output: string;
+});
+
+// Stop current generation
+chat.stop();
+```
+
+### File Attachments
+
+```typescript
+// HTML template
+<input type="file" multiple (change)="onFileSelect($event)" />
+
+// Component
+onFileSelect(event: Event) {
+  const files = (event.target as HTMLInputElement).files;
+  if (files) {
+    this.chat.sendMessage({
+      text: "Analyze these files",
+      files: files
+    });
+  }
+}
+```
+
+### Client-side Tool Calls
+
+```typescript
+const chat = new Chat({
+  async onToolCall({ toolCall }) {
+    switch (toolCall.toolName) {
+      case 'get_weather':
+        return await getWeather(toolCall.input.location);
+      case 'search':
+        return await search(toolCall.input.query);
+      default:
+        throw new Error(`Unknown tool: ${toolCall.toolName}`);
+    }
+  },
+});
+```
+
+## Completion
+
+Single-turn text generation with streaming.
+
+### Basic Usage
+
+```typescript
+import { Component } from '@angular/core';
+import { Completion } from '@ai-sdk/angular';
+
+@Component({
+  selector: 'app-completion',
+  template: `
+    <div>
+      <textarea
+        [(ngModel)]="completion.input"
+        placeholder="Enter your prompt..."
+        rows="4"
+      >
+      </textarea>
+
+      <button
+        (click)="completion.complete(completion.input)"
+        [disabled]="completion.loading"
+      >
+        {{ completion.loading ? 'Generating...' : 'Generate' }}
+      </button>
+
+      @if (completion.loading) {
+        <button (click)="completion.stop()">Stop</button>
+      }
+
+      <div class="result">
+        <h3>Result:</h3>
+        <pre>{{ completion.completion }}</pre>
+      </div>
+
+      @if (completion.error) {
+        <div class="error">{{ completion.error.message }}</div>
+      }
+    </div>
+  `,
+})
+export class CompletionComponent {
+  completion = new Completion({
+    api: '/api/completion',
+    onFinish: (prompt, completion) => {
+      console.log('Completed:', { prompt, completion });
+    },
+  });
+}
+```
+
+### Constructor Options
+
+```typescript
+interface CompletionOptions {
+  /** API endpoint (default: '/api/completion') */
+  api?: string;
+
+  /** Unique identifier */
+  id?: string;
+
+  /** Initial completion text */
+  initialCompletion?: string;
+
+  /** Initial input text */
+  initialInput?: string;
+
+  /** Stream protocol: 'data' (default) | 'text' */
+  streamProtocol?: 'data' | 'text';
+
+  /** Completion callback */
+  onFinish?: (prompt: string, completion: string) => void;
+
+  /** Error handler */
+  onError?: (error: Error) => void;
+
+  /** Custom fetch function */
+  fetch?: FetchFunction;
+
+  /** Request headers */
+  headers?: Record<string, string>;
+
+  /** Request body */
+  body?: Record<string, any>;
+
+  /** Request credentials */
+  credentials?: RequestCredentials;
+}
+```
+
+### Properties (Reactive)
+
+- `completion: string` - Generated text (writable)
+- `input: string` - Current input (writable)
+- `loading: boolean` - Generation state
+- `error: Error | undefined` - Error state
+- `id: string` - Completion ID
+- `api: string` - API endpoint
+- `streamProtocol: 'data' | 'text'` - Stream type
+
+### Methods
+
+```typescript
+// Generate completion
+await completion.complete(
+  prompt: string,
+  options?: {
+    headers?: Record<string, string>;
+    body?: Record<string, any>;
+  }
+);
+
+// Form submission handler
+await completion.handleSubmit(event?: { preventDefault?: () => void });
+
+// Stop generation
+completion.stop();
+```
+
+## StructuredObject
+
+Generate structured data with Zod schemas and streaming.
+
+### Basic Usage
+
+```typescript
+import { Component } from '@angular/core';
+import { StructuredObject } from '@ai-sdk/angular';
+import { z } from 'zod';
+
+const schema = z.object({
+  title: z.string(),
+  summary: z.string(),
+  tags: z.array(z.string()),
+  sentiment: z.enum(['positive', 'negative', 'neutral']),
+});
+
+@Component({
+  selector: 'app-structured-object',
+  template: `
+    <div>
+      <textarea
+        [(ngModel)]="input"
+        placeholder="Enter content to analyze..."
+        rows="4"
+      >
+      </textarea>
+
+      <button (click)="analyze()" [disabled]="structuredObject.loading">
+        {{ structuredObject.loading ? 'Analyzing...' : 'Analyze' }}
+      </button>
+
+      @if (structuredObject.object) {
+        <div class="result">
+          <h3>Analysis:</h3>
+          <div><strong>Title:</strong> {{ structuredObject.object.title }}</div>
+          <div>
+            <strong>Summary:</strong> {{ structuredObject.object.summary }}
+          </div>
+          <div>
+            <strong>Tags:</strong>
+            {{ structuredObject.object.tags?.join(', ') }}
+          </div>
+          <div>
+            <strong>Sentiment:</strong> {{ structuredObject.object.sentiment }}
+          </div>
+        </div>
+      }
+
+      @if (structuredObject.error) {
+        <div class="error">{{ structuredObject.error.message }}</div>
+      }
+    </div>
+  `,
+})
+export class StructuredObjectComponent {
+  input = '';
+
+  structuredObject = new StructuredObject({
+    api: '/api/analyze',
+    schema,
+    onFinish: ({ object, error }) => {
+      if (error) {
+        console.error('Schema validation failed:', error);
+      } else {
+        console.log('Generated object:', object);
+      }
+    },
+  });
+
+  async analyze() {
+    if (!this.input.trim()) return;
+    await this.structuredObject.submit(this.input);
+  }
+}
+```
+
+### Constructor Options
+
+```typescript
+interface StructuredObjectOptions<SCHEMA, RESULT> {
+  /** API endpoint */
+  api: string;
+
+  /** Zod schema */
+  schema: SCHEMA;
+
+  /** Unique identifier */
+  id?: string;
+
+  /** Initial object value */
+  initialValue?: DeepPartial<RESULT>;
+
+  /** Completion callback */
+  onFinish?: (event: {
+    object: RESULT | undefined;
+    error: Error | undefined;
+  }) => void;
+
+  /** Error handler */
+  onError?: (error: Error) => void;
+
+  /** Custom fetch function */
+  fetch?: FetchFunction;
+
+  /** Request headers */
+  headers?: Record<string, string>;
+
+  /** Request credentials */
+  credentials?: RequestCredentials;
+}
+```
+
+### Properties (Reactive)
+
+- `object: DeepPartial<RESULT> | undefined` - Generated object
+- `loading: boolean` - Generation state
+- `error: Error | undefined` - Error state
+
+### Methods
+
+```typescript
+// Submit input for generation
+await structuredObject.submit(input: unknown);
+
+// Stop generation
+structuredObject.stop();
+```
+
+## Server Implementation
+
+### Express.js Chat Endpoint
+
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { convertToModelMessages, streamText } from 'ai';
+import express from 'express';
+
+const app = express();
+app.use(express.json());
+
+app.post('/api/chat', async (req, res) => {
+  const { messages, selectedModel } = req.body;
+
+  const result = streamText({
+    model: openai(selectedModel || 'gpt-4o'),
+    messages: convertToModelMessages(messages),
+  });
+
+  result.pipeUIMessageStreamToResponse(res);
+});
+```
+
+### Express.js Completion Endpoint
+
+```typescript
+app.post('/api/completion', async (req, res) => {
+  const { prompt } = req.body;
+
+  const result = streamText({
+    model: openai('gpt-4o'),
+    prompt,
+  });
+
+  result.pipeTextStreamToResponse(res);
+});
+```
+
+### Express.js Structured Object Endpoint
+
+```typescript
+import { streamObject } from 'ai';
+import { z } from 'zod';
+
+app.post('/api/analyze', async (req, res) => {
+  const input = req.body;
+
+  const result = streamObject({
+    model: openai('gpt-4o'),
+    schema: z.object({
+      title: z.string(),
+      summary: z.string(),
+      tags: z.array(z.string()),
+      sentiment: z.enum(['positive', 'negative', 'neutral']),
+    }),
+    prompt: `Analyze this content: ${JSON.stringify(input)}`,
+  });
+
+  result.pipeTextStreamToResponse(res);
+});
+```
+
+## Development Setup
+
+### Building the Library
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build library
+pnpm build
+
+# Watch mode
+pnpm build:watch
+
+# Run tests
+pnpm test
+
+# Test watch mode
+pnpm test:watch
+```
+
+### Running the Example
+
+```bash
+# Navigate to example
+cd examples/angular-chat
+
+# Set up environment
+echo "OPENAI_API_KEY=your_key_here" > .env
+
+# Start development (Angular + Express)
+pnpm start
+```
+
+Starts:
+
+- Angular dev server: `http://localhost:4200`
+- Express API server: `http://localhost:3000`
+- Proxy routes `/api/*` to Express
+
+## Testing
+
+### Running Tests
+
+```bash
+pnpm test              # Run all tests
+pnpm test:watch        # Watch mode
+pnpm test:update       # Update snapshots
+```
+
+## TypeScript Support
+
+Full type safety with automatic type inference:
+
+```typescript
+import { Chat, UIMessage, StructuredObject } from '@ai-sdk/angular';
+import { z } from 'zod';
+
+// Custom message types
+interface CustomMessage extends UIMessage {
+  customData?: string;
+}
+
+const chat = new Chat<CustomMessage>({});
+
+// Schema-typed objects
+const schema = z.object({
+  name: z.string(),
+  age: z.number(),
+});
+
+const obj = new StructuredObject({
+  api: '/api/object',
+  schema, // Type automatically inferred
+});
+
+// obj.object has type: { name?: string; age?: number } | undefined
+```
+
+## Error Handling
+
+All components provide reactive error states:
+
+```typescript
+const chat = new Chat({
+  onError: (error) => {
+    console.error('Chat error:', error);
+  }
+});
+
+// Template
+@if (chat.error) {
+  <div class="error">{{ chat.error.message }}</div>
+}
+```
+
+## Performance
+
+### Stop on-going requests
+
+```typescript
+chat.stop();
+completion.stop();
+structuredObject.stop();
+```
+
+### Change Detection
+
+Uses Angular signals for efficient reactivity:
+
+```typescript
+// These trigger minimal change detection
+chat.messages; // Signal<UIMessage[]>
+chat.status; // Signal<ChatStatus>
+chat.error; // Signal<Error | undefined>
+```
+
+## License
+
+Apache-2.0