@ulam/halohalo 0.1.0

package/README.md

@@ -0,0 +1,193 @@
+# @ulam/halohalo
+
+AI service adapters, model configuration, and provider abstraction. Vanilla core with a React hooks adapter.
+
+Named for halo-halo, the Filipino shaved ice dessert: a mix of many things that somehow works together.
+
+## The ulam framework
+
+```text
+ulam
+├── @ulam/halohalo     mixed  : AI provider adapters  ← you are here
+├── @ulam/taho         warm   : ARIA live region announcer
+├── @ulam/sili         hot    : focus management, overlays, routing
+├── @ulam/calamansi    sour   : i18n, hooks, utilities, logic
+├── @ulam/ube          sweet  : React UI components, theming
+└── @ulam/sawsawan     bridge : wires the above together
+```
+
+## 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` |
+
+## License
+
+MIT

package/agenticAiService.js

@@ -0,0 +1,76 @@
+import { callAnthropicWithTools } from './fetch.js'
+import { makeSearchTool } from './search.js'
+import { getAdapter } from '@ulam/sawsawan'
+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 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

@@ -0,0 +1,31 @@
+import { callProvider } from './fetch.js'
+import { getAdapter } from '@ulam/sawsawan'
+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 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)
+}

package/angular.js

@@ -0,0 +1,102 @@
+/**
+ * @ulam/halohalo/angular: Angular adapter
+ *
+ * Injectable services wrapping the vanilla halohalo core with Angular signal
+ * reactivity. Provide once at the application root via provideHalohalo().
+ */
+import { Injectable, signal, computed } from '@angular/core'
+import { createCompletion } from './createCompletion.js'
+import { createProviderConfig } from './createProviderConfig.js'
+
+/**
+ * Service for AI completions. Each inject() call gets its own completion
+ * instance; loading/animating state is per-instance.
+ *
+ * Usage:
+ *   private completion = inject(CompletionService)
+ *
+ *   await this.completion.complete({ prompt: 'Rewrite for mobile.' })
+ *   // this.completion.loading() is true while running
+ */
+@Injectable()
+export class CompletionService {
+  #instance = createCompletion()
+  #loading = signal(false)
+  #animating = signal(false)
+
+  loading = computed(() => this.#loading())
+  animating = computed(() => this.#animating())
+
+  constructor() {
+    this.#instance.subscribe(({ loading, animating }) => {
+      this.#loading.set(loading)
+      this.#animating.set(animating)
+    })
+  }
+
+  complete(options) {
+    return this.#instance.complete(options)
+  }
+
+  cancel() {
+    this.#instance.cancel()
+  }
+
+  ngOnDestroy() {
+    this.#instance.cancel()
+  }
+}
+
+/**
+ * Service for AI provider and model configuration. One config store per application.
+ *
+ * Usage:
+ *   private providerConfig = inject(ProviderConfigService)
+ *
+ *   this.providerConfig.setProvider('openai')
+ *   const current = this.providerConfig.provider()   // Signal<string>
+ */
+@Injectable({ providedIn: 'root' })
+export class ProviderConfigService {
+  #config = createProviderConfig()
+  #provider = signal(this.#config.provider)
+  #models = signal(this.#config.models)
+  #mode = signal(this.#config.mode)
+
+  provider = computed(() => this.#provider())
+  models = computed(() => this.#models())
+  mode = computed(() => this.#mode())
+  providers = this.#config.providers
+
+  constructor() {
+    this.#config.subscribe(() => {
+      this.#provider.set(this.#config.provider)
+      this.#models.set(this.#config.models)
+      this.#mode.set(this.#config.mode)
+    })
+  }
+
+  setProvider(id) { this.#config.setProvider(id) }
+  setModel(pid, mid) { this.#config.setModel(pid, mid) }
+  setMode(v) { this.#config.setMode(v) }
+  setKey(pid, v) { return this.#config.setKey(pid, v) }
+  getKey(pid) { return this.#config.getKey(pid) }
+  getModel(pid) { return this.#config.getModel(pid) }
+  getLabel(pid) { return this.#config.getLabel(pid) }
+}
+
+/**
+ * Standalone provider function. Use in bootstrapApplication() or as a
+ * component-level provider when you need scoped completion instances.
+ *
+ * App-level (shared singleton):
+ *   bootstrapApplication(AppComponent, {
+ *     providers: [provideHalohalo()]
+ *   })
+ *
+ * Component-level (scoped instance):
+ *   @Component({ providers: [CompletionService] })
+ */
+export function provideHalohalo() {
+  return [ProviderConfigService, CompletionService]
+}

package/connectivity.js

@@ -0,0 +1,17 @@
+/**
+ * Probes a list of endpoints in parallel to check network reachability.
+ *
+ * @param {Array<{ label: string, url: string }>} probes
+ * @param {number} [timeoutMs=4000]
+ * @returns {Promise<Array<{ label: string, ok: boolean }>>}
+ */
+export async function checkConnectivity(probes, timeoutMs = 4000) {
+  const results = await Promise.allSettled(
+    probes.map(p =>
+      fetch(p.url, { method: 'HEAD', mode: 'no-cors', signal: AbortSignal.timeout(timeoutMs) })
+        .then(() => ({ label: p.label, ok: true }))
+        .catch(() => ({ label: p.label, ok: false }))
+    )
+  )
+  return results.map(r => r.value || r.reason)
+}

package/constants.js

@@ -0,0 +1,43 @@
+export const LS_AI_PROVIDER      = 'ai_provider'
+export const LS_AGENTIC_MODE     = 'agentic_mode'
+export const LS_APIKEY_PREFIX    = 'apikey_'
+export const LS_AI_MODEL_PREFIX  = 'ai_model_'
+
+export const AI_MAX_TOKENS          = 1024
+export const AI_AGENTIC_MAX_TOKENS  = 2048
+export const AGENTIC_MAX_TOOL_TURNS = 5
+
+export const ANTHROPIC_API_VERSION = '2023-06-01'
+export const ANTHROPIC_API_URL     = 'https://api.anthropic.com/v1/messages'
+
+export const AI_DESC_REGEX = /^Description:\s*(.+)/m
+export const AI_FIX_REGEX  = /^Suggested Fix:\s*(.+)/ms
+
+export const DEBUG_AI_DELAY_MS = 1200
+
+export const DEFAULT_AI_MODELS = {
+  anthropic: 'claude-sonnet-4-6',
+  openai:    'gpt-4o',
+  google:    'gemini-1.5-flash',
+  microsoft: '',
+}
+
+export const PROVIDER_LABELS = {
+  anthropic: 'Claude',
+  openai:    'GPT',
+  google:    'Gemini',
+  microsoft: 'Copilot',
+}
+
+export const DEBUG_COMMANDS = Object.freeze({
+  OK:            'debug ok',
+  WRONG:         'debug wrong',
+  AUTH:          'debug 401',
+  RATE:          'debug 429',
+  SERVICE:       'debug 503',
+  NETWORK:       'debug network',
+  AI_ASSIST_ON:  'debug ai assist on',
+  AI_ASSIST_OFF: 'debug ai assist off',
+})
+
+export const DEBUG_COMMAND_VALUES = Object.freeze(Object.values(DEBUG_COMMANDS))

package/createCompletion.js

@@ -0,0 +1,113 @@
+import { callProvider, callAnthropicWithTools } from './fetch.js'
+import { AiApiError } from './providers.js'
+
+const DEFAULT_TYPEWRITER = { tickMs: 33, minCharsPerTick: 2, charDivisor: 40 }
+
+/**
+ * Vanilla completion runner. No React required.
+ * Returns { complete(options), cancel() } plus a subscribe() for state changes.
+ *
+ * State: { loading: boolean, animating: boolean }
+ *
+ * options for complete():
+ *   provider, model, key, prompt, maxTokens: for standard completions
+ *   agentOptions: { system, tools, messages, maxTurns, onToolCall }: for agentic
+ *   onResult(fields)       : called with parsed result after completion
+ *   onError(error)         : called with AiApiError on failure
+ *   parseResponse(text)    : maps raw text to result fields object
+ *   typewriter             : { tickMs, minCharsPerTick, charDivisor } or false
+ *   onAnimate(field, text) : called each tick with field + current text slice
+ *   onAnimateDone()        : called when typewriter finishes
+ */
+export function createCompletion() {
+  let loading = false
+  let animating = false
+  let timer = null
+  const listeners = new Set()
+  const notify = () => listeners.forEach(fn => fn({ loading, animating }))
+
+  function runTypewriter(fields, { typewriter, onAnimate, onAnimateDone }) {
+    clearTimeout(timer)
+    const { tickMs, minCharsPerTick, charDivisor } = { ...DEFAULT_TYPEWRITER, ...typewriter }
+
+    const entries = Object.entries(fields).filter(([, v]) => typeof v === 'string' && v.length > 0)
+    if (!entries.length) {
+      animating = false
+      notify()
+      onAnimateDone?.()
+      return
+    }
+
+    const total = entries.reduce((sum, [, v]) => sum + v.length, 0)
+    const charsPerTick = Math.max(minCharsPerTick, Math.ceil(total / charDivisor))
+    const indices = Object.fromEntries(entries.map(([k]) => [k, 0]))
+    let entryIdx = 0
+
+    function tick() {
+      const [field, text] = entries[entryIdx]
+      indices[field] = Math.min(indices[field] + charsPerTick, text.length)
+      onAnimate?.(field, text.slice(0, indices[field]))
+      if (indices[field] >= text.length) entryIdx++
+      if (entryIdx >= entries.length) {
+        animating = false
+        notify()
+        onAnimateDone?.()
+      } else {
+        timer = setTimeout(tick, tickMs)
+      }
+    }
+
+    timer = setTimeout(tick, tickMs)
+  }
+
+  return {
+    get loading() { return loading },
+    get animating() { return animating },
+
+    subscribe(fn) {
+      listeners.add(fn)
+      return () => listeners.delete(fn)
+    },
+
+    async complete({ provider, model, key, prompt, maxTokens, agentOptions, onResult, onError, parseResponse, typewriter = DEFAULT_TYPEWRITER, onAnimate, onAnimateDone }) {
+      loading = true
+      notify()
+
+      try {
+        let text
+        if (agentOptions) {
+          const { system, tools, messages, maxTurns, onToolCall } = agentOptions
+          text = await callAnthropicWithTools({ key, model, system, tools, messages, maxTokens, maxTurns, onToolCall })
+        } else {
+          text = await callProvider({ provider, model, key, prompt, maxTokens })
+        }
+
+        const result = parseResponse ? parseResponse(text) : { text }
+        loading = false
+
+        if (typewriter && onAnimate) {
+          animating = true
+          notify()
+          onResult?.(result)
+          runTypewriter(result, { typewriter, onAnimate, onAnimateDone })
+        } else {
+          notify()
+          onResult?.(result)
+          onAnimateDone?.()
+        }
+      } catch (e) {
+        loading = false
+        animating = false
+        notify()
+        onError?.(e instanceof AiApiError ? e : new AiApiError('api_error'))
+      }
+    },
+
+    cancel() {
+      clearTimeout(timer)
+      loading = false
+      animating = false
+      notify()
+    },
+  }
+}

package/createProviderConfig.js

@@ -0,0 +1,80 @@
+import { DEFAULT_MODELS, DEFAULT_PROVIDERS, DEFAULT_PROVIDER_LABELS } from './providers.js'
+import { getAdapter } from '@ulam/sawsawan'
+
+/**
+ * Vanilla provider config store. No React required.
+ * Returns a plain object with getters, setters, and a subscribe() for change notifications.
+ *
+ * storageKeys: { provider, modelPrefix, keyPrefix, mode? }
+ * providers: optional array of { id, label, defaultModel? }
+ */
+export function createProviderConfig(storageKeys, providers = DEFAULT_PROVIDERS) {
+  const { provider: providerKey, modelPrefix, keyPrefix, mode: modeKey } = storageKeys
+
+  const providerList = providers.map(p =>
+    typeof p === 'string' ? { id: p, label: DEFAULT_PROVIDER_LABELS[p] || p } : p
+  )
+
+  let provider = getAdapter().readPref(providerKey) || providerList[0]?.id || 'anthropic'
+
+  let models = Object.fromEntries(
+    providerList.map(p => [
+      p.id,
+      getAdapter().readPref(`${modelPrefix}${p.id}`) || p.defaultModel || DEFAULT_MODELS[p.id] || '',
+    ])
+  )
+
+  let mode = modeKey ? getAdapter().readPref(modeKey) === 'true' : false
+
+  const listeners = new Set()
+  const notify = () => listeners.forEach(fn => fn())
+
+  return {
+    get provider() { return provider },
+    get models() { return { ...models } },
+    get mode() { return mode },
+    get providers() { return providerList },
+
+    setProvider(id) {
+      getAdapter().writePref(providerKey, id)
+      provider = id
+      notify()
+    },
+
+    setModel(providerId, modelId) {
+      getAdapter().writePref(`${modelPrefix}${providerId}`, modelId)
+      models = { ...models, [providerId]: modelId }
+      notify()
+    },
+
+    setMode(value) {
+      if (!modeKey) return
+      getAdapter().writePref(modeKey, value ? 'true' : 'false')
+      mode = value
+      notify()
+    },
+
+    async setKey(providerId, value) {
+      await getAdapter().setKey(`${keyPrefix}${providerId}`, value)
+    },
+
+    async getKey(providerId) {
+      return (await getAdapter().getKey(`${keyPrefix}${providerId}`)) || ''
+    },
+
+    getModel(providerId) {
+      return models[providerId] || DEFAULT_MODELS[providerId] || ''
+    },
+
+    getLabel(providerId) {
+      return providerList.find(p => p.id === providerId)?.label
+        || DEFAULT_PROVIDER_LABELS[providerId]
+        || providerId
+    },
+
+    subscribe(fn) {
+      listeners.add(fn)
+      return () => listeners.delete(fn)
+    },
+  }
+}

package/fetch.js

@@ -0,0 +1,113 @@
+import { AiApiError, httpStatusToErrorType, PROVIDER_CONFIGS } from './providers.js'
+
+// ─── callProvider ─────────────────────────────────────────────────────────────
+// Single-turn completion against any configured provider.
+// Returns the response text string.
+
+export async function callProvider({ provider, model, key, prompt, maxTokens = 1024 }) {
+  const config = PROVIDER_CONFIGS[provider]
+  if (!config) throw new AiApiError('api_error', { provider })
+
+  let url
+  if (config.buildUrl) {
+    url = config.buildUrl(key, model)
+    if (!url) throw new AiApiError('api_error', { provider })
+  } else {
+    url = config.url
+  }
+
+  let res
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: config.buildHeaders(key),
+      body: config.buildBody(prompt, model, maxTokens),
+    })
+  } catch {
+    throw new AiApiError('network_error', { provider })
+  }
+
+  if (!res.ok) {
+    throw new AiApiError(httpStatusToErrorType(res.status), { status: res.status, provider })
+  }
+
+  return config.parseResponse(res)
+}
+
+// ─── callAnthropicWithTools ───────────────────────────────────────────────────
+// Agentic tool-use loop for Anthropic. Calls the messages API repeatedly until
+// stop_reason is 'end_turn' or maxTurns is exhausted.
+//
+// onToolCall(toolName, toolInput) => toolResultContent (string or object)
+// Returns the final text block content.
+
+export async function callAnthropicWithTools({
+  key,
+  model,
+  system,
+  tools,
+  messages,
+  maxTokens = 2048,
+  maxTurns = 5,
+  onToolCall,
+}) {
+  const config = PROVIDER_CONFIGS.anthropic
+  let turns = 0
+
+  while (turns <= maxTurns) {
+    let res
+    try {
+      res = await fetch(config.url, {
+        method: 'POST',
+        headers: config.buildHeaders(key),
+        body: JSON.stringify({ model, max_tokens: maxTokens, system, tools, messages }),
+      })
+    } catch {
+      throw new AiApiError('network_error', { provider: 'anthropic' })
+    }
+
+    if (!res.ok) {
+      throw new AiApiError(httpStatusToErrorType(res.status), { status: res.status, provider: 'anthropic' })
+    }
+
+    const data = await res.json()
+
+    if (import.meta.env.DEV) console.log(`[halohalo] turn ${turns + 1}, stop_reason: ${data.stop_reason}`)
+
+    messages.push({ role: 'assistant', content: data.content })
+
+    if (data.stop_reason === 'end_turn') {
+      return data.content.find(b => b.type === 'text')?.text || ''
+    }
+
+    if (data.stop_reason === 'tool_use') {
+      if (turns >= maxTurns) {
+        if (import.meta.env.DEV) console.warn('[halohalo] maxTurns reached')
+        throw new AiApiError('api_error', { provider: 'anthropic' })
+      }
+
+      const toolBlocks = data.content.filter(b => b.type === 'tool_use')
+      const toolResults = await Promise.all(
+        toolBlocks.map(async (block) => {
+          const result = await onToolCall?.(block.name, block.input) ?? ''
+          if (import.meta.env.DEV) {
+            console.log(`[halohalo] tool_use: ${block.name}`, block.input, '→', result)
+          }
+          return {
+            type: 'tool_result',
+            tool_use_id: block.id,
+            content: typeof result === 'string' ? result : JSON.stringify(result),
+          }
+        })
+      )
+
+      messages.push({ role: 'user', content: toolResults })
+      turns++
+      continue
+    }
+
+    break
+  }
+
+  throw new AiApiError('api_error', { provider: 'anthropic' })
+}

package/index.js

@@ -0,0 +1,20 @@
+// vanilla core
+export { initHalohalo } from './init.js'
+export { AiApiError, httpStatusToErrorType, PROVIDER_CONFIGS } from './providers.js'
+export { callProvider, callAnthropicWithTools } from './fetch.js'
+export { searchItems, makeSearchTool } from './search.js'
+export { createProviderConfig } from './createProviderConfig.js'
+export { createCompletion } from './createCompletion.js'
+export { getAiRefinement, parseAiResponse } from './aiService.js'
+export { getAgenticRefinement } from './agenticAiService.js'
+export { PROVIDERS, PROVIDER_MODELS, initModels, initApiKeys } from './models.js'
+export { getAiProvider, isAgenticModeEnabled, getAiModel, getProviderLabel } from './prefs.js'
+export { checkConnectivity } from './connectivity.js'
+export {
+  LS_AI_PROVIDER, LS_AGENTIC_MODE, LS_APIKEY_PREFIX, LS_AI_MODEL_PREFIX,
+  AI_MAX_TOKENS, AI_AGENTIC_MAX_TOKENS, AGENTIC_MAX_TOOL_TURNS,
+  AI_DESC_REGEX, AI_FIX_REGEX,
+  DEBUG_AI_DELAY_MS, DEFAULT_AI_MODELS, PROVIDER_LABELS,
+  DEBUG_COMMANDS, DEBUG_COMMAND_VALUES,
+  ANTHROPIC_API_VERSION, ANTHROPIC_API_URL,
+} from './constants.js'

package/init.js

@@ -0,0 +1,33 @@
+// ─── halohalo module singleton ────────────────────────────────────────────────
+// Holds app-injected config. Call initHalohalo() before using aiService or
+// agenticAiService.
+
+let _buildPrompt = null
+let _systemPrompt = null
+
+/**
+ * Register app-specific AI config. Call once at app init.
+ *
+ * @param {{
+ *   buildPrompt: (params: object) => string,
+ *   systemPrompt?: string,
+ * }} config
+ *
+ * buildPrompt receives { finding, descText, fixText, note } and must return
+ * the user-turn prompt string for single-turn refinement.
+ *
+ * systemPrompt is used for agentic (tool-use) mode. If omitted, agentic mode
+ * falls back to a generic instruction.
+ */
+export function initHalohalo({ buildPrompt, systemPrompt = null }) {
+  _buildPrompt = buildPrompt
+  _systemPrompt = systemPrompt
+}
+
+export function getBuildPrompt() {
+  return _buildPrompt
+}
+
+export function getSystemPrompt() {
+  return _systemPrompt
+}

package/models.js

@@ -0,0 +1,38 @@
+import { getAdapter } from '@ulam/sawsawan'
+import { LS_AI_MODEL_PREFIX, LS_APIKEY_PREFIX, DEFAULT_AI_MODELS } from './constants.js'
+
+export const PROVIDERS = [
+  { id: 'anthropic', label: 'Anthropic (Claude)', placeholderKey: 'settings.api_placeholder_anthropic' },
+  { id: 'openai',    label: 'OpenAI (GPT)',        placeholderKey: 'settings.api_placeholder_openai'    },
+  { id: 'google',    label: 'Google (Gemini)',      placeholderKey: 'settings.api_placeholder_google'    },
+  { id: 'microsoft', label: 'Microsoft (Copilot)', placeholderKey: 'settings.api_placeholder_default'   },
+]
+
+export const PROVIDER_MODELS = {
+  anthropic: [
+    { id: 'claude-haiku-4-5-20251001', label: 'Claude Haiku 4.5, fast, low cost' },
+    { id: 'claude-sonnet-4-6',         label: 'Claude Sonnet 4.6, balanced (default)' },
+    { id: 'claude-opus-4-7',           label: 'Claude Opus 4.7, most capable' },
+  ],
+  openai: [
+    { id: 'gpt-4o-mini', label: 'GPT-4o Mini, fast, low cost' },
+    { id: 'gpt-4o',      label: 'GPT-4o, balanced (default)' },
+  ],
+  google: [
+    { id: 'gemini-1.5-flash', label: 'Gemini 1.5 Flash, fast (default)' },
+    { id: 'gemini-1.5-pro',   label: 'Gemini 1.5 Pro, most capable' },
+  ],
+  microsoft: [],
+}
+
+export function initModels() {
+  return Object.fromEntries(
+    PROVIDERS.map(p => [p.id, getAdapter().readPref(`${LS_AI_MODEL_PREFIX}${p.id}`) || DEFAULT_AI_MODELS[p.id] || ''])
+  )
+}
+
+export function initApiKeys() {
+  return Object.fromEntries(
+    PROVIDERS.map(p => [p.id, window.electronAPI ? '' : getAdapter().readPref(`${LS_APIKEY_PREFIX}${p.id}`) || ''])
+  )
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ulam/halohalo",
+  "version": "0.1.0",
+  "description": "AI service adapters, model configuration, and provider abstraction.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mikeyil/ulam.git",
+    "directory": "packages/halohalo"
+  },
+  "keywords": ["ai", "llm", "anthropic", "openai", "react", "vue", "angular", "hooks", "ulam"],
+  "exports": {
+    ".": "./index.js",
+    "./react": "./react.js",
+    "./vue": "./vue.js",
+    "./angular": "./angular.js"
+  },
+  "files": ["*.js", "README.md"],
+  "peerDependencies": {
+    "react": ">=18",
+    "vue": ">=3",
+    "@angular/core": ">=17",
+    "fuse.js": ">=7",
+    "@ulam/sawsawan": "*"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "vue": { "optional": true },
+    "@angular/core": { "optional": true },
+    "fuse.js": { "optional": true },
+    "@ulam/sawsawan": { "optional": true }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/prefs.js

@@ -0,0 +1,17 @@
+import { LS_AI_PROVIDER, LS_AI_MODEL_PREFIX, LS_AGENTIC_MODE, DEFAULT_AI_MODELS, PROVIDER_LABELS } from './constants.js'
+
+export function getAiProvider() {
+  return localStorage.getItem(LS_AI_PROVIDER) || 'anthropic'
+}
+
+export function isAgenticModeEnabled() {
+  return localStorage.getItem(LS_AGENTIC_MODE) === 'true'
+}
+
+export function getAiModel(provider) {
+  return localStorage.getItem(`${LS_AI_MODEL_PREFIX}${provider}`) || DEFAULT_AI_MODELS[provider] || ''
+}
+
+export function getProviderLabel(provider) {
+  return PROVIDER_LABELS[provider] || provider
+}

package/providers.js

@@ -0,0 +1,108 @@
+// ─── Error types ─────────────────────────────────────────────────────────────
+
+export class AiApiError extends Error {
+  /** @param {'invalid_key'|'rate_limit'|'service_error'|'network_error'|'api_error'} type */
+  constructor(type, { status, provider } = {}) {
+    super(`AiApiError: ${type}`)
+    this.type = type
+    this.status = status
+    this.provider = provider
+  }
+}
+
+export function httpStatusToErrorType(status) {
+  if (status === 401 || status === 403) return 'invalid_key'
+  if (status === 429) return 'rate_limit'
+  if (status >= 500) return 'service_error'
+  return 'api_error'
+}
+
+// ─── Provider configs ─────────────────────────────────────────────────────────
+// Each entry describes how to build headers, body, and parse responses for a
+// given AI provider. getModel is injected at call time so the config itself
+// carries no storage dependency.
+
+export const PROVIDER_CONFIGS = {
+  anthropic: {
+    url: 'https://api.anthropic.com/v1/messages',
+    buildHeaders: (key) => ({
+      'Content-Type': 'application/json',
+      'x-api-key': key,
+      'anthropic-version': '2023-06-01',
+      'anthropic-dangerous-direct-browser-access': 'true',
+    }),
+    buildBody: (prompt, model, maxTokens) => JSON.stringify({
+      model,
+      max_tokens: maxTokens,
+      messages: [{ role: 'user', content: prompt }],
+    }),
+    parseResponse: async (res) => {
+      const data = await res.json()
+      return data.content?.[0]?.text || ''
+    },
+  },
+
+  openai: {
+    url: 'https://api.openai.com/v1/chat/completions',
+    buildHeaders: (key) => ({
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${key}`,
+    }),
+    buildBody: (prompt, model, maxTokens) => JSON.stringify({
+      model,
+      max_tokens: maxTokens,
+      messages: [{ role: 'user', content: prompt }],
+    }),
+    parseResponse: async (res) => {
+      const data = await res.json()
+      return data.choices?.[0]?.message?.content || ''
+    },
+  },
+
+  google: {
+    buildUrl: (key, model) =>
+      `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${key}`,
+    buildHeaders: () => ({ 'Content-Type': 'application/json' }),
+    buildBody: (prompt, _model, maxTokens) => JSON.stringify({
+      contents: [{ parts: [{ text: prompt }] }],
+      generationConfig: { maxOutputTokens: maxTokens },
+    }),
+    parseResponse: async (res) => {
+      const data = await res.json()
+      return data.candidates?.[0]?.content?.parts?.[0]?.text || ''
+    },
+  },
+
+  microsoft: {
+    // Requires VITE_AZURE_OPENAI_ENDPOINT set to your Azure deployment URL.
+    buildUrl: () => import.meta.env.VITE_AZURE_OPENAI_ENDPOINT || null,
+    buildHeaders: (key) => ({
+      'Content-Type': 'application/json',
+      'api-key': key,
+    }),
+    buildBody: (prompt, _model, maxTokens) => JSON.stringify({
+      max_tokens: maxTokens,
+      messages: [{ role: 'user', content: prompt }],
+    }),
+    parseResponse: async (res) => {
+      const data = await res.json()
+      return data.choices?.[0]?.message?.content || ''
+    },
+  },
+}
+
+export const DEFAULT_PROVIDERS = ['anthropic', 'openai', 'google', 'microsoft']
+
+export const DEFAULT_MODELS = {
+  anthropic: 'claude-sonnet-4-6',
+  openai:    'gpt-4o',
+  google:    'gemini-1.5-flash',
+  microsoft: '',
+}
+
+export const DEFAULT_PROVIDER_LABELS = {
+  anthropic: 'Claude',
+  openai:    'GPT',
+  google:    'Gemini',
+  microsoft: 'Copilot',
+}

package/react.js

@@ -0,0 +1,2 @@
+export { useProviderConfig } from './useProviderConfig.js'
+export { useCompletion } from './useCompletion.js'

package/search.js

@@ -0,0 +1,63 @@
+import Fuse from 'fuse.js'
+
+// ─── searchItems ──────────────────────────────────────────────────────────────
+// Generic Fuse.js search over any corpus array.
+// fields     : Fuse key/weight config: [{ name, weight }, ...]
+// Returns simplified result objects containing only the requested fields.
+
+export function searchItems(query, corpus, { fields, threshold = 0.4, minMatchCharLength = 2, limit = 3, pick } = {}) {
+  if (!query?.trim() || !Array.isArray(corpus) || corpus.length === 0) return []
+
+  const fuse = new Fuse(corpus, {
+    keys: fields,
+    threshold,
+    minMatchCharLength,
+    includeScore: true,
+  })
+
+  const results = fuse.search(query.trim()).slice(0, limit).map(r => r.item)
+
+  if (pick) return results.map(item => Object.fromEntries(pick.map(k => [k, item[k]])))
+  return results
+}
+
+// ─── makeSearchTool ───────────────────────────────────────────────────────────
+// Builds an Anthropic tool-use schema + handler pair for a corpus search tool.
+// The returned { schema, handler } can be passed directly to callAnthropicWithTools.
+//
+// options.name        : tool name (default: 'search_corpus')
+// options.description : tool description string
+// options.fields      : Fuse key/weight config
+// options.pick        : fields to include in returned results
+// options.limit       : max results (default: 3)
+
+export function makeSearchTool(corpus, options = {}) {
+  const {
+    name = 'search_corpus',
+    description = 'Search the corpus for entries related to a natural-language query.',
+    queryDescription = 'Natural-language search query.',
+    fields,
+    pick,
+    limit = 3,
+    threshold,
+    minMatchCharLength,
+  } = options
+
+  const schema = {
+    name,
+    description,
+    input_schema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: queryDescription },
+      },
+      required: ['query'],
+    },
+  }
+
+  function handler(_toolName, input) {
+    return searchItems(input?.query ?? '', corpus, { fields, pick, limit, threshold, minMatchCharLength })
+  }
+
+  return { schema, handler }
+}

package/useCompletion.js

@@ -0,0 +1,17 @@
+import { useState, useEffect } from 'react'
+import { createCompletion } from './createCompletion.js'
+
+export function useCompletion(options = {}) {
+  const [instance] = useState(createCompletion)
+  const [state, setState] = useState({ loading: false, animating: false })
+
+  useEffect(() => instance.subscribe(setState), [instance])
+  useEffect(() => () => instance.cancel(), [instance])
+
+  return {
+    loading: state.loading,
+    animating: state.animating,
+    complete: (callOptions) => instance.complete({ ...options, ...callOptions }),
+    cancel: () => instance.cancel(),
+  }
+}

package/useProviderConfig.js

@@ -0,0 +1,22 @@
+import { useState, useCallback, useEffect } from 'react'
+import { createProviderConfig } from './createProviderConfig.js'
+
+export function useProviderConfig(storageKeys, providers) {
+  const [config] = useState(() => createProviderConfig(storageKeys, providers))
+  const [, rerender] = useState(0)
+  useEffect(() => config.subscribe(() => rerender(n => n + 1)), [config])
+
+  return {
+    provider: config.provider,
+    models: config.models,
+    mode: config.mode,
+    providers: config.providers,
+    setProvider: useCallback((id) => config.setProvider(id), [config]),
+    setModel: useCallback((pid, mid) => config.setModel(pid, mid), [config]),
+    setMode: useCallback((v) => config.setMode(v), [config]),
+    setKey: useCallback((pid, v) => config.setKey(pid, v), [config]),
+    getKey: useCallback((pid) => config.getKey(pid), [config]),
+    getModel: useCallback((pid) => config.getModel(pid), [config]),
+    getLabel: useCallback((pid) => config.getLabel(pid), [config]),
+  }
+}

package/vue.js

@@ -0,0 +1,73 @@
+/**
+ * @ulam/halohalo/vue: Vue composables adapter
+ */
+import { ref, readonly } from 'vue'
+import { createCompletion } from './createCompletion.js'
+import { createProviderConfig } from './createProviderConfig.js'
+
+/**
+ * Reactive wrapper around createCompletion(). Returns reactive loading and
+ * animating state, plus complete() and cancel() functions.
+ *
+ * @param {object} [defaultOptions] - default options merged into every complete() call
+ */
+export function useCompletion(defaultOptions = {}) {
+  const instance = createCompletion()
+  const loading = ref(false)
+  const animating = ref(false)
+
+  const unsubscribe = instance.subscribe(({ loading: l, animating: a }) => {
+    loading.value = l
+    animating.value = a
+  })
+
+  // caller should invoke cleanup() in onUnmounted if used inside a component
+  function cleanup() {
+    instance.cancel()
+    unsubscribe()
+  }
+
+  return {
+    loading: readonly(loading),
+    animating: readonly(animating),
+    complete: (callOptions) => instance.complete({ ...defaultOptions, ...callOptions }),
+    cancel: () => instance.cancel(),
+    cleanup,
+  }
+}
+
+/**
+ * Reactive wrapper around createProviderConfig(). All config fields are reactive
+ * refs; setters update the underlying singleton and trigger re-reads.
+ *
+ * @param {object} [storageKeys]
+ * @param {Array}  [providers]
+ */
+export function useProviderConfig(storageKeys, providers) {
+  const config = createProviderConfig(storageKeys, providers)
+
+  const provider = ref(config.provider)
+  const models = ref(config.models)
+  const mode = ref(config.mode)
+
+  const unsubscribe = config.subscribe(() => {
+    provider.value = config.provider
+    models.value = config.models
+    mode.value = config.mode
+  })
+
+  return {
+    provider: readonly(provider),
+    models: readonly(models),
+    mode: readonly(mode),
+    providers: config.providers,
+    setProvider: (id) => config.setProvider(id),
+    setModel: (pid, mid) => config.setModel(pid, mid),
+    setMode: (v) => config.setMode(v),
+    setKey: (pid, v) => config.setKey(pid, v),
+    getKey: (pid) => config.getKey(pid),
+    getModel: (pid) => config.getModel(pid),
+    getLabel: (pid) => config.getLabel(pid),
+    cleanup: unsubscribe,
+  }
+}