@voicelayer/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 VoiceLayer
+
+   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,286 @@
+# @voicelayer/sdk
+
+> Build voice AI agents that run real business processes — in one file.
+
+```bash
+# The SDK is lean. Providers (STT / TTS / LLM / VAD / turn detection) install
+# separately, so you only pull in the vendors you actually use. These four are
+# the default pipeline:
+pnpm add @voicelayer/sdk \
+  @voicelayer/agents-plugin-deepgram \
+  @voicelayer/agents-plugin-openai \
+  @voicelayer/agents-plugin-silero \
+  @voicelayer/agents-plugin-livekit
+```
+
+See [Providers](#providers) for the full list. Use a provider you haven't
+installed and the SDK throws a single, actionable error telling you what to add.
+
+## Hello, voice agent (30 seconds)
+
+```ts
+// agent.ts
+import { defineAgent } from '@voicelayer/sdk';
+
+export default await defineAgent({
+  name: 'hello',
+  prompt: 'You are a friendly receptionist. Ask the caller how you can help.',
+}).start(import.meta.url);
+```
+
+```bash
+node --import tsx agent.ts dev
+```
+
+Call your LiveKit number. The agent answers. That's it. STT, LLM, TTS, VAD, turn detection — defaults are picked for you. Swap them later with one config line.
+
+---
+
+## A real agent (FNOL in 100 lines)
+
+The voice plumbing isn't the hard part. The hard part is running a **business process** to completion: collecting required fields, validating them, escalating on legal threats, persisting memory across calls, handing off to a human, and writing the result back to your CRM.
+
+That's what this SDK does. One declaration:
+
+```ts
+import { defineAgent, defineProcess } from '@voicelayer/sdk';
+import { salesforce } from '@voicelayer/connector-salesforce';
+
+export default await defineAgent({
+  name: 'fnol',
+  prompt: 'You are a calm First Notice of Loss intake agent.',
+
+  // 1. The business process. Declarative — the SDK extracts fields from
+  //    each utterance, validates them, and decides when the call can end.
+  process: defineProcess({
+    collect: {
+      incidentDate:     { type: 'datetime', required: true },
+      vehiclesInvolved: { type: 'string[]', required: true, min: 1 },
+      injuries:         { type: 'boolean',  required: true },
+      policeReport:     { type: 'boolean' },
+      claimNumber:      { type: 'string',   required: true, pattern: /^[A-Z]{2}-\d{8}$/ },
+    },
+    completeWhen: 'all-required-captured',
+    onComplete: async (data, ctx) => {
+      const claim = await ctx.connectors.salesforce.createClaim(data);
+      await ctx.say(`Your claim number is ${claim.id}. You will receive a text shortly.`);
+    },
+  }),
+
+  // 2. Triggers — fire deterministically before the LLM sees the turn.
+  triggers: {
+    legalThreat:  { on: /\b(attorney|lawyer|sue|lawsuit)\b/i, then: 'handoff' },
+    severeInjury: { on: 'signal:medical_emergency',          then: 'handoff' },
+  },
+
+  // 3. Handoff — real SIP transfer, with state briefing for the human agent.
+  handoff: {
+    fallback: '+15555550100',
+    briefing: ({ data, transcript }) =>
+      `Caller reported FNOL. Captured: ${JSON.stringify(data)}. Last 3 turns: ${transcript.tail(3)}`,
+  },
+
+  // 4. Memory — persisted across calls, scoped to the caller. PII auto-redacted.
+  memory: {
+    scope: 'caller',
+    retentionDays: 90,
+    piiFields: ['ssn', 'dob'],
+  },
+
+  // 5. Connectors — auto-wired tools, available to the LLM and in ctx.
+  connectors: {
+    salesforce: salesforce({ objects: ['Claim', 'Account'] }),
+  },
+
+  // 6. Compliance — opt-in posture, defaults are safe.
+  compliance: ['tcpa'],
+}).start(import.meta.url);
+```
+
+**That's a complete production FNOL agent.** 60 lines of config, no boilerplate. Same file runs in dev and prod. Same file is what LiveKit forks for each call.
+
+---
+
+## Mental model
+
+You declare **one Agent**. The Agent has six knobs:
+
+| Knob          | What it does                                                       |
+|---------------|--------------------------------------------------------------------|
+| `prompt`      | What the LLM says when nothing else fires.                         |
+| `process`     | The structured outcome the call exists to produce.                 |
+| `triggers`    | Deterministic routes that run *before* the LLM (regex, signals).   |
+| `handoff`     | How to transfer to a human, with what context.                     |
+| `memory`      | What persists across calls, scoped, with PII rules.                |
+| `connectors`  | Typed external systems the agent can read/write.                   |
+
+Everything else (STT, TTS, LLM, VAD, turn detection, transcript persistence, security guards, telemetry) is **on by default** with sane choices, and swappable in one line when you need to.
+
+---
+
+## Three tiers of customization
+
+**Tier 1 — Config only.** Covers ~80% of voice agents. The example above is Tier 1.
+
+**Tier 2 — Hooks.** When config isn't enough, drop into hooks. Same agent, same file:
+
+```ts
+defineAgent({
+  // ...
+  async onUtterance(text, ctx) {
+    if (text.includes('refund')) ctx.metadata.flagged = true;
+  },
+  async onFieldCaptured(field, value, ctx) {
+    if (field === 'claimNumber') await ctx.connectors.salesforce.lookup(value);
+  },
+  async onCallEnd(outcome, ctx) {
+    await ctx.connectors.slack.send(`#claims`, `Call ${ctx.call.id} ended: ${outcome.reason}`);
+  },
+});
+```
+
+**Tier 3 — Full control.** When hooks aren't enough, take the wheel:
+
+```ts
+defineAgent({
+  // ...
+  async onCall(ctx) {
+    // You own the entire conversation loop.
+    await ctx.say('Hi! What is your policy number?');
+    const policy = await ctx.ask();
+    const account = await ctx.connectors.salesforce.lookupPolicy(policy);
+    // ... do whatever ...
+  },
+});
+```
+
+You never have to leave the SDK. You never import a `primitive`.
+
+---
+
+## Swapping models
+
+Each provider is a small factory you import from the SDK. Pick the pieces you
+want; the SDK wires them into the pipeline:
+
+```ts
+import { defineAgent, deepgram, openai, cartesia } from '@voicelayer/sdk';
+
+defineAgent({
+  // ...
+  models: {
+    stt: deepgram.stt({ model: 'nova-3' }),
+    llm: openai.llm({ model: 'gpt-4o' }),
+    tts: cartesia.tts({ voice: 'sonic-english' }), // pnpm add @voicelayer/agents-plugin-cartesia
+  },
+});
+```
+
+Provider plugins load lazily — the vendor SDK (and its native binaries) only
+loads on first use, never at import time.
+
+## Providers
+
+Install only what you use:
+
+| Provider | Package | Factory |
+|----------|---------|---------|
+| Deepgram (STT, TTS) | `@voicelayer/agents-plugin-deepgram` | `deepgram.stt()`, `deepgram.tts()` |
+| OpenAI (LLM, TTS, Realtime) | `@voicelayer/agents-plugin-openai` | `openai.llm()`, `openai.tts()`, `openai.realtime()` |
+| Cartesia (TTS, STT) | `@voicelayer/agents-plugin-cartesia` | `cartesia.tts()`, `cartesia.stt()` |
+| ElevenLabs (TTS) | `@voicelayer/agents-plugin-elevenlabs` | `elevenlabs.tts()` |
+| AssemblyAI (STT) | `@voicelayer/agents-plugin-assemblyai` | `assemblyai.stt()` |
+| Google Gemini (LLM, Realtime) | `@voicelayer/agents-plugin-google` | `google.llm()`, `google.realtime()` |
+| Silero (VAD) | `@voicelayer/agents-plugin-silero` | `silero.vad()` |
+| LiveKit (turn detection) | `@voicelayer/agents-plugin-livekit` | `livekitTurn.english()`, `livekitTurn.multilingual()` |
+
+Each is a thin, versioned wrapper over the matching `@livekit/agents-plugin-*`
+package. Need a provider that isn't listed? Wrap any LiveKit plugin instance
+with `wrap(...)`, or implement the `STTProvider` / `LLMProvider` / `TTSProvider`
+interfaces directly.
+
+---
+
+## Connectors
+
+Connectors are **typed integrations** with external systems. They show up on `ctx.connectors` and (optionally) as LLM tools.
+
+```ts
+import { salesforce, twilio, slack, zendesk, webhook } from '@voicelayer/connectors';
+
+defineAgent({
+  // ...
+  connectors: {
+    crm:    salesforce({ objects: ['Claim'] }),
+    sms:    twilio(),
+    alerts: slack({ channel: '#claims' }),
+    custom: webhook({ url: 'https://your-api.example.com/voicelayer' }),
+  },
+});
+```
+
+Available connectors: `salesforce`, `twilio`, `slack`, `zendesk`, `webhook`, `epic` (HIPAA-scoped), `servicenow`. More on the roadmap.
+
+---
+
+## Testing locally
+
+```ts
+import { testAgent } from '@voicelayer/sdk/testing';
+import agent from './agent.js';
+
+test('captures all required fields', async () => {
+  const result = await testAgent(agent)
+    .say('I was in a wreck yesterday with my Honda Civic, no injuries.')
+    .say('Claim number is AB-12345678.')
+    .end();
+
+  expect(result.process.complete).toBe(true);
+  expect(result.process.data.vehiclesInvolved).toEqual(['Honda Civic']);
+});
+```
+
+No LiveKit, no audio, no API keys. Pure unit-test speed.
+
+---
+
+## Production
+
+`await start(import.meta.url)` boots a LiveKit worker in the parent process and exports the resolved LiveKit agent definition for the child job runner that re-imports the same file. The same file. No deploy pipeline differences between local and prod beyond environment variables.
+
+```bash
+# Required:
+export VOICELAYER_API_KEY=...
+export LIVEKIT_URL=...
+export LIVEKIT_API_KEY=...
+export LIVEKIT_API_SECRET=...
+export OPENAI_API_KEY=...
+export DEEPGRAM_API_KEY=...
+
+node agent.ts start
+```
+
+---
+
+## What's *not* in this SDK
+
+- No "primitive" packages to import. The internal modularity is the platform team's problem, not yours.
+- No multi-file boilerplate. One file per agent.
+- No state-machine framework you have to learn. `process` is a field bag with validation; `triggers` are if/then rules. If you need branching flows, you use `onUtterance` or `onCall`.
+- No "agent vs module" distinction. One declaration, one mental model.
+
+---
+
+## Stability
+
+The SDK is currently **`0.x`**. APIs may change between minor versions while we find product-market fit. We will document every breaking change in the changelog.
+
+At `1.0` we'll commit to semver and a stable public surface. Until then, expect movement.
+
+---
+
+## Reference
+
+- API: [`docs/API.md`](../../docs/API.md)
+- Architecture (what's underneath): [`docs/architecture.md`](../../docs/architecture.md)
+- Migration from 0.x → 0.next: [`CHANGELOG.md`](./CHANGELOG.md)