@ulam/halohalo 0.3.2 → 0.3.3

package/README.md

@@ -1,212 +1,212 @@
-# @ulam/halohalo
-
-AI service adapters, model configuration, and provider abstraction. Vanilla core with React, Vue, and Angular adapters.
-
-Named for halo-halo, the Filipino shaved ice dessert: a mix of many things that somehow works together.
-
-## Purpose & Scope
-
-**What halohalo does:**
-
-- Provider abstraction for Anthropic, OpenAI, and Google
-- API key management (localStorage-backed, never sent to server)
-- Model selection and configuration per provider
-- Completion calls with consistent interface across providers
-- Tool calling and agentic mode for complex operations
-- Framework-agnostic vanilla core with framework adapters
-- Zero build-time provider detection or configuration
-
-**What halohalo doesn't do:**
-
-- Message history or conversation management (bring your own state)
-- Streaming response handling (returns complete results)
-- Rate limiting or retry logic (use middleware patterns for these)
-- Token counting or pricing calculation (external concerns)
-- API key validation or rotation (user responsibility)
-- Multi-user authentication or access control
-
-**Who should use halohalo:**
-
-- Apps that need multiple AI provider support with runtime switching
-- Projects storing API keys client-side (browser-only, no backend)
-- Vanilla JavaScript, React, Vue, or Angular apps using AI features
-- Applications wanting provider-agnostic completion calls
-- Teams integrating AI features without external API servers
-
-## The ulam Framework
-
-Halohalo is one of six independent packages in the ulam framework. See [docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md) for the complete framework structure and dependency graph.
-
-## Install
-
-```bash
-npm install @ulam/halohalo
-```
-
-Peer dependencies: `fuse.js >= 7` (for search). Framework adapters add `react >= 18`, `vue >= 3`, or `@angular/core >= 17` as needed.
-
-## Supported providers
-
-- Anthropic (Claude)
-- OpenAI (GPT)
-- Google (Gemini)
-
-Bring your own API key. Keys stay in the browser via localStorage and are sent directly to the provider, never to a server.
-
-## Usage
-
-### Initialize
-
-```js
-import { initApiKeys, initModels, getAiProvider } from '@ulam/halohalo'
-
-initApiKeys({ anthropic: 'sk-ant-...', openai: 'sk-...' })
-initModels({ anthropic: 'claude-sonnet-4-6', openai: 'gpt-4o' })
-
-const provider = getAiProvider() // 'anthropic' | 'openai' | 'google'
-```
-
-### Call a provider
-
-```js
-import { createCompletion } from '@ulam/halohalo'
-
-const result = await createCompletion({
-  prompt: 'Rewrite this finding for a mobile context.',
-  systemPrompt: 'You are an accessibility audit assistant.',
-})
-```
-
-### Anthropic with tool use
-
-```js
-import { callAnthropicWithTools } from '@ulam/halohalo'
-
-const result = await callAnthropicWithTools({
-  messages,
-  tools,
-  system: 'You are an accessibility audit assistant.',
-})
-```
-
-### Agentic mode
-
-Agentic mode uses tool calling to search the corpus for similar past revisions before rewriting, matching the tone and depth of established work.
-
-```js
-import { getAgenticRefinement } from '@ulam/halohalo'
-
-const revised = await getAgenticRefinement({
-  finding,
-  notes: 'This is specific to mobile, element is a tooltip',
-})
-```
-
-### React hooks adapter
-
-```jsx
-import { useProviderConfig, useCompletion } from '@ulam/halohalo/react'
-
-function AISettings() {
-  const { provider, model, setProvider } = useProviderConfig()
-  const { complete, loading } = useCompletion()
-
-  return (
-    <button onClick={() => complete('Rewrite this for mobile.')}>
-      {loading ? 'Revising...' : 'Rewrite'}
-    </button>
-  )
-}
-```
-
-### Vue composables adapter
-
-`@ulam/halohalo/vue` provides composables that wrap the vanilla `createCompletion` and `createProviderConfig` with Vue reactivity. Loading and animating state are `readonly` refs that update as the completion runs.
-
-```js
-import { useCompletion, useProviderConfig } from '@ulam/halohalo/vue'
-import { onUnmounted } from 'vue'
-
-// In setup()
-const { loading, animating, complete, cancel, cleanup } = useCompletion()
-onUnmounted(cleanup)
-
-// loading.value and animating.value are reactive
-await complete({ prompt: 'Rewrite this for mobile.' })
-```
-
-`useProviderConfig()` returns reactive refs for `provider`, `models`, and `mode`, plus all setter functions from the vanilla config store.
-
-```js
-const { provider, setProvider } = useProviderConfig()
-// provider.value is reactive
-setProvider('openai')
-```
-
-Both composables return a `cleanup` function. Call it in `onUnmounted()` if the composable is used inside a component. For app-level use outside a component, cleanup is optional.
-
-### Angular services adapter
-
-`@ulam/halohalo/angular` provides two injectable services backed by Angular signals.
-
-**`CompletionService`** is not `providedIn: 'root'`. Each injection creates a separate completion instance with its own loading state. Provide it at the component level for scoped instances, or at the application level for a shared one.
-
-```ts
-import { CompletionService, ProviderConfigService, provideHalohalo } from '@ulam/halohalo/angular'
-
-// Application root (shared singleton):
-bootstrapApplication(AppComponent, {
-  providers: [provideHalohalo()]
-})
-
-// Or component-level (scoped per component):
-@Component({
-  providers: [CompletionService],
-  template: `
-    <button (click)="rewrite()" [disabled]="completion.loading()">
-      {{ completion.loading() ? 'Revising...' : 'Rewrite' }}
-    </button>
-  `
-})
-export class RewriteButtonComponent {
-  completion = inject(CompletionService)
-
-  async rewrite() {
-    await this.completion.complete({ prompt: 'Rewrite for mobile.' })
-  }
-}
-```
-
-`completion.loading()` and `completion.animating()` are Angular `computed` signals that work directly in templates and in `effect()` calls.
-
-**`ProviderConfigService`** is `providedIn: 'root'`, giving you one config store for the whole app.
-
-```ts
-@Component({ ... })
-export class SettingsComponent {
-  providerConfig = inject(ProviderConfigService)
-
-  // In template:
-  // {{ providerConfig.provider() }}
-  // (click)="providerConfig.setProvider('openai')"
-}
-```
-
-## Design
-
-**Bring your own key.** No proxy, no server, no account. API keys are stored in localStorage and sent directly to the provider.
-
-**Provider-agnostic core.** `createCompletion` works the same regardless of which provider is active. Switch providers without changing call sites.
-
-**Vanilla-first.** The core has no framework dependency. Import from `/react`, `/vue`, or `/angular` only when you need framework reactivity.
-
-## Subpath exports
-
-| Import | Contents |
-| ------ | -------- |
-| `@ulam/halohalo` | Vanilla core: `createCompletion`, `createProviderConfig`, `callProvider`, `callAnthropicWithTools`, `getAgenticRefinement`, `searchItems`, `makeSearchTool`, and more |
-| `@ulam/halohalo/react` | `useCompletion`, `useProviderConfig` |
-| `@ulam/halohalo/vue` | `useCompletion`, `useProviderConfig` |
-| `@ulam/halohalo/angular` | `CompletionService`, `ProviderConfigService`, `provideHalohalo` |
-
-See the [root README](../../README.md) for a complete framework support overview across all ulam packages.
+# @ulam/halohalo
+
+AI service adapters, model configuration, and provider abstraction. Vanilla core with React, Vue, and Angular adapters.
+
+Named for halo-halo, the Filipino shaved ice dessert: a mix of many things that somehow works together.
+
+## Purpose & Scope
+
+**What halohalo does:**
+
+- Provider abstraction for Anthropic, OpenAI, and Google
+- API key management (localStorage-backed, never sent to server)
+- Model selection and configuration per provider
+- Completion calls with consistent interface across providers
+- Tool calling and agentic mode for complex operations
+- Framework-agnostic vanilla core with framework adapters
+- Zero build-time provider detection or configuration
+
+**What halohalo doesn't do:**
+
+- Message history or conversation management (bring your own state)
+- Streaming response handling (returns complete results)
+- Rate limiting or retry logic (use middleware patterns for these)
+- Token counting or pricing calculation (external concerns)
+- API key validation or rotation (user responsibility)
+- Multi-user authentication or access control
+
+**Who should use halohalo:**
+
+- Apps that need multiple AI provider support with runtime switching
+- Projects storing API keys client-side (browser-only, no backend)
+- Vanilla JavaScript, React, Vue, or Angular apps using AI features
+- Applications wanting provider-agnostic completion calls
+- Teams integrating AI features without external API servers
+
+## The ulam Framework
+
+Halohalo is one of six independent packages in the ulam framework. See [docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md) for the complete framework structure and dependency graph.
+
+## Install
+
+```bash
+npm install @ulam/halohalo
+```
+
+Peer dependencies: `fuse.js >= 7` (for search). Framework adapters add `react >= 18`, `vue >= 3`, or `@angular/core >= 17` as needed.
+
+## Supported providers
+
+- Anthropic (Claude)
+- OpenAI (GPT)
+- Google (Gemini)
+
+Bring your own API key. Keys stay in the browser via localStorage and are sent directly to the provider, never to a server.
+
+## Usage
+
+### Initialize
+
+```js
+import { initApiKeys, initModels, getAiProvider } from '@ulam/halohalo'
+
+initApiKeys({ anthropic: 'sk-ant-...', openai: 'sk-...' })
+initModels({ anthropic: 'claude-sonnet-4-6', openai: 'gpt-4o' })
+
+const provider = getAiProvider() // 'anthropic' | 'openai' | 'google'
+```
+
+### Call a provider
+
+```js
+import { createCompletion } from '@ulam/halohalo'
+
+const result = await createCompletion({
+  prompt: 'Rewrite this finding for a mobile context.',
+  systemPrompt: 'You are an accessibility audit assistant.',
+})
+```
+
+### Anthropic with tool use
+
+```js
+import { callAnthropicWithTools } from '@ulam/halohalo'
+
+const result = await callAnthropicWithTools({
+  messages,
+  tools,
+  system: 'You are an accessibility audit assistant.',
+})
+```
+
+### Agentic mode
+
+Agentic mode uses tool calling to search the corpus for similar past revisions before rewriting, matching the tone and depth of established work.
+
+```js
+import { getAgenticRefinement } from '@ulam/halohalo'
+
+const revised = await getAgenticRefinement({
+  finding,
+  notes: 'This is specific to mobile, element is a tooltip',
+})
+```
+
+### React hooks adapter
+
+```jsx
+import { useProviderConfig, useCompletion } from '@ulam/halohalo/react'
+
+function AISettings() {
+  const { provider, model, setProvider } = useProviderConfig()
+  const { complete, loading } = useCompletion()
+
+  return (
+    <button onClick={() => complete('Rewrite this for mobile.')}>
+      {loading ? 'Revising...' : 'Rewrite'}
+    </button>
+  )
+}
+```
+
+### Vue composables adapter
+
+`@ulam/halohalo/vue` provides composables that wrap the vanilla `createCompletion` and `createProviderConfig` with Vue reactivity. Loading and animating state are `readonly` refs that update as the completion runs.
+
+```js
+import { useCompletion, useProviderConfig } from '@ulam/halohalo/vue'
+import { onUnmounted } from 'vue'
+
+// In setup()
+const { loading, animating, complete, cancel, cleanup } = useCompletion()
+onUnmounted(cleanup)
+
+// loading.value and animating.value are reactive
+await complete({ prompt: 'Rewrite this for mobile.' })
+```
+
+`useProviderConfig()` returns reactive refs for `provider`, `models`, and `mode`, plus all setter functions from the vanilla config store.
+
+```js
+const { provider, setProvider } = useProviderConfig()
+// provider.value is reactive
+setProvider('openai')
+```
+
+Both composables return a `cleanup` function. Call it in `onUnmounted()` if the composable is used inside a component. For app-level use outside a component, cleanup is optional.
+
+### Angular services adapter
+
+`@ulam/halohalo/angular` provides two injectable services backed by Angular signals.
+
+**`CompletionService`** is not `providedIn: 'root'`. Each injection creates a separate completion instance with its own loading state. Provide it at the component level for scoped instances, or at the application level for a shared one.
+
+```ts
+import { CompletionService, ProviderConfigService, provideHalohalo } from '@ulam/halohalo/angular'
+
+// Application root (shared singleton):
+bootstrapApplication(AppComponent, {
+  providers: [provideHalohalo()]
+})
+
+// Or component-level (scoped per component):
+@Component({
+  providers: [CompletionService],
+  template: `
+    <button (click)="rewrite()" [disabled]="completion.loading()">
+      {{ completion.loading() ? 'Revising...' : 'Rewrite' }}
+    </button>
+  `
+})
+export class RewriteButtonComponent {
+  completion = inject(CompletionService)
+
+  async rewrite() {
+    await this.completion.complete({ prompt: 'Rewrite for mobile.' })
+  }
+}
+```
+
+`completion.loading()` and `completion.animating()` are Angular `computed` signals that work directly in templates and in `effect()` calls.
+
+**`ProviderConfigService`** is `providedIn: 'root'`, giving you one config store for the whole app.
+
+```ts
+@Component({ ... })
+export class SettingsComponent {
+  providerConfig = inject(ProviderConfigService)
+
+  // In template:
+  // {{ providerConfig.provider() }}
+  // (click)="providerConfig.setProvider('openai')"
+}
+```
+
+## Design
+
+**Bring your own key.** No proxy, no server, no account. API keys are stored in localStorage and sent directly to the provider.
+
+**Provider-agnostic core.** `createCompletion` works the same regardless of which provider is active. Switch providers without changing call sites.
+
+**Vanilla-first.** The core has no framework dependency. Import from `/react`, `/vue`, or `/angular` only when you need framework reactivity.
+
+## Subpath exports
+
+| Import | Contents |
+| ------ | -------- |
+| `@ulam/halohalo` | Vanilla core: `createCompletion`, `createProviderConfig`, `callProvider`, `callAnthropicWithTools`, `getAgenticRefinement`, `searchItems`, `makeSearchTool`, and more |
+| `@ulam/halohalo/react` | `useCompletion`, `useProviderConfig` |
+| `@ulam/halohalo/vue` | `useCompletion`, `useProviderConfig` |
+| `@ulam/halohalo/angular` | `CompletionService`, `ProviderConfigService`, `provideHalohalo` |
+
+See the [root README](../../README.md) for a complete framework support overview across all ulam packages.

package/agenticAiService.js

@@ -1,76 +1,76 @@
-import { callAnthropicWithTools } from './fetch.js'
-import { makeSearchTool } from './search.js'
-import { AI_AGENTIC_MAX_TOKENS, AGENTIC_MAX_TOOL_TURNS, LS_APIKEY_PREFIX } from './constants.js'
-import { getAiModel } from './prefs.js'
-import { parseAiResponse } from './aiService.js'
-import { getSystemPrompt } from './init.js'
-
-export { AiApiError } from './providers.js'
-
-const FALLBACK_SYSTEM_PROMPT = `You are an AI assistant helping rewrite text entries based on user notes. Search for related entries before rewriting, then produce a revised description and suggested fix.
-
-Format your final output as exactly two lines:
-Description: [rewritten description]
-Suggested Fix: [rewritten suggested fix]`
-
-const CORPUS_SEARCH_FIELDS = [
-  { name: 'title',    weight: 0.32 },
-  { name: 'keywords', weight: 0.30 },
-  { name: 'desc',     weight: 0.07 },
-  { name: 'fix',      weight: 0.03 },
-]
-
-const CORPUS_PICK = ['id', 'title', 'primarySC', 'severity', 'desc', 'fix']
-
-export async function getAgenticRefinement({ finding, descText, fixText, note, corpus }) {
-  const { getAdapter } = await import('@ulam/sawsawan')
-  const key = await getAdapter().getKey(`${LS_APIKEY_PREFIX}anthropic`)
-
-  if (!key) throw new Error('Anthropic API key required for agentic mode. Add one in Settings → AI Assist.')
-
-  const model = getAiModel('anthropic')
-
-  const { schema: toolSchema, handler: toolHandler } = makeSearchTool(corpus, {
-    name: 'search_corpus',
-    description:
-      'Search the accessibility finding corpus for entries related to a natural-language query. ' +
-      'Call this before rewriting to find similar findings that demonstrate the expected voice, ' +
-      'tone, and technical depth. Returns up to 3 matching entries.',
-    queryDescription: 'Natural-language search query, e.g. "keyboard focus visible" or "color contrast low vision".',
-    fields: CORPUS_SEARCH_FIELDS,
-    pick: CORPUS_PICK,
-    limit: 3,
-  })
-
-  const userPrompt = `Refine this accessibility finding based on the auditor's note.
-
-Title: ${finding.title}
-WCAG SC: ${finding.primarySC}
-Severity: ${finding.severity}
-Platform: ${finding.platform}
-
-Current description:
-${descText}
-
-Current suggested fix:
-${fixText}
-
-Auditor's note: "${note}"
-
-Search the corpus for related findings, then rewrite the description and suggested fix to reflect the refinement.`
-
-  const messages = [{ role: 'user', content: userPrompt }]
-
-  const text = await callAnthropicWithTools({
-    key,
-    model,
-    system: getSystemPrompt() || FALLBACK_SYSTEM_PROMPT,
-    tools: [toolSchema],
-    messages,
-    maxTokens: AI_AGENTIC_MAX_TOKENS,
-    maxTurns: AGENTIC_MAX_TOOL_TURNS,
-    onToolCall: toolHandler,
-  })
-
-  return parseAiResponse(text)
-}
+import { callAnthropicWithTools } from './fetch.js'
+import { makeSearchTool } from './search.js'
+import { AI_AGENTIC_MAX_TOKENS, AGENTIC_MAX_TOOL_TURNS, LS_APIKEY_PREFIX } from './constants.js'
+import { getAiModel } from './prefs.js'
+import { parseAiResponse } from './aiService.js'
+import { getSystemPrompt } from './init.js'
+
+export { AiApiError } from './providers.js'
+
+const FALLBACK_SYSTEM_PROMPT = `You are an AI assistant helping rewrite text entries based on user notes. Search for related entries before rewriting, then produce a revised description and suggested fix.
+
+Format your final output as exactly two lines:
+Description: [rewritten description]
+Suggested Fix: [rewritten suggested fix]`
+
+const CORPUS_SEARCH_FIELDS = [
+  { name: 'title',    weight: 0.32 },
+  { name: 'keywords', weight: 0.30 },
+  { name: 'desc',     weight: 0.07 },
+  { name: 'fix',      weight: 0.03 },
+]
+
+const CORPUS_PICK = ['id', 'title', 'primarySC', 'severity', 'desc', 'fix']
+
+export async function getAgenticRefinement({ finding, descText, fixText, note, corpus }) {
+  const { getAdapter } = await import('@ulam/sawsawan')
+  const key = await getAdapter().getKey(`${LS_APIKEY_PREFIX}anthropic`)
+
+  if (!key) throw new Error('Anthropic API key required for agentic mode. Add one in Settings → AI Assist.')
+
+  const model = getAiModel('anthropic')
+
+  const { schema: toolSchema, handler: toolHandler } = makeSearchTool(corpus, {
+    name: 'search_corpus',
+    description:
+      'Search the accessibility finding corpus for entries related to a natural-language query. ' +
+      'Call this before rewriting to find similar findings that demonstrate the expected voice, ' +
+      'tone, and technical depth. Returns up to 3 matching entries.',
+    queryDescription: 'Natural-language search query, e.g. "keyboard focus visible" or "color contrast low vision".',
+    fields: CORPUS_SEARCH_FIELDS,
+    pick: CORPUS_PICK,
+    limit: 3,
+  })
+
+  const userPrompt = `Refine this accessibility finding based on the auditor's note.
+
+Title: ${finding.title}
+WCAG SC: ${finding.primarySC}
+Severity: ${finding.severity}
+Platform: ${finding.platform}
+
+Current description:
+${descText}
+
+Current suggested fix:
+${fixText}
+
+Auditor's note: "${note}"
+
+Search the corpus for related findings, then rewrite the description and suggested fix to reflect the refinement.`
+
+  const messages = [{ role: 'user', content: userPrompt }]
+
+  const text = await callAnthropicWithTools({
+    key,
+    model,
+    system: getSystemPrompt() || FALLBACK_SYSTEM_PROMPT,
+    tools: [toolSchema],
+    messages,
+    maxTokens: AI_AGENTIC_MAX_TOKENS,
+    maxTurns: AGENTIC_MAX_TOOL_TURNS,
+    onToolCall: toolHandler,
+  })
+
+  return parseAiResponse(text)
+}

package/aiService.js

@@ -1,31 +1,31 @@
-import { callProvider } from './fetch.js'
-import { AI_MAX_TOKENS, AI_DESC_REGEX, AI_FIX_REGEX, LS_APIKEY_PREFIX } from './constants.js'
-import { getAiProvider, getAiModel } from './prefs.js'
-import { getBuildPrompt } from './init.js'
-
-export { AiApiError, httpStatusToErrorType } from './providers.js'
-
-export function parseAiResponse(text) {
-  const descMatch = text.match(AI_DESC_REGEX)
-  const fixMatch  = text.match(AI_FIX_REGEX)
-  return {
-    desc: descMatch?.[1]?.trim() || null,
-    fix:  fixMatch?.[1]?.trim()  || null,
-  }
-}
-
-export async function getAiRefinement({ finding, descText, fixText, note }) {
-  const buildPrompt = getBuildPrompt()
-  if (!buildPrompt) throw new Error('halohalo: call initHalohalo({ buildPrompt }) before getAiRefinement')
-
-  const provider = getAiProvider()
-  const { getAdapter } = await import('@ulam/sawsawan')
-  const key = await getAdapter().getKey(`${LS_APIKEY_PREFIX}${provider}`)
-
-  if (!key) throw new Error(`No API key found for ${provider}. Add one in Settings.`)
-
-  const model = getAiModel(provider)
-  const prompt = buildPrompt({ finding, descText, fixText, note })
-  const text = await callProvider({ provider, model, key, prompt, maxTokens: AI_MAX_TOKENS })
-  return parseAiResponse(text)
-}
+import { callProvider } from './fetch.js'
+import { AI_MAX_TOKENS, AI_DESC_REGEX, AI_FIX_REGEX, LS_APIKEY_PREFIX } from './constants.js'
+import { getAiProvider, getAiModel } from './prefs.js'
+import { getBuildPrompt } from './init.js'
+
+export { AiApiError, httpStatusToErrorType } from './providers.js'
+
+export function parseAiResponse(text) {
+  const descMatch = text.match(AI_DESC_REGEX)
+  const fixMatch  = text.match(AI_FIX_REGEX)
+  return {
+    desc: descMatch?.[1]?.trim() || null,
+    fix:  fixMatch?.[1]?.trim()  || null,
+  }
+}
+
+export async function getAiRefinement({ finding, descText, fixText, note }) {
+  const buildPrompt = getBuildPrompt()
+  if (!buildPrompt) throw new Error('halohalo: call initHalohalo({ buildPrompt }) before getAiRefinement')
+
+  const provider = getAiProvider()
+  const { getAdapter } = await import('@ulam/sawsawan')
+  const key = await getAdapter().getKey(`${LS_APIKEY_PREFIX}${provider}`)
+
+  if (!key) throw new Error(`No API key found for ${provider}. Add one in Settings.`)
+
+  const model = getAiModel(provider)
+  const prompt = buildPrompt({ finding, descText, fixText, note })
+  const text = await callProvider({ provider, model, key, prompt, maxTokens: AI_MAX_TOKENS })
+  return parseAiResponse(text)
+}