langwire

AI-powered language conversation toolkit for CEFR-aware practice with gentle corrections and vocabulary tracking.

Live demo: https://langwire.vercel.app

Demo app source: https://github.com/v1onues/langwire/tree/main/demo

Installation

npm install langwire

Quick Start

import "dotenv/config";
import { LangWire } from "langwire";

async function run() {
  const apiKey = process.env.ANTHROPIC_API_KEY;

  if (!apiKey) {
    throw new Error("Missing ANTHROPIC_API_KEY in .env");
  }

  const langWire = new LangWire({
    targetLang: "en",
    nativeLang: "tr",
    level: "A1",
    scenario: "daily_chat",
    apiKey
  });

  const messages = [
    "Merhaba! Benim adim Veli.",
    "I am like coffee and book.",
    "Can you help me introduce myself in English?"
  ];

  for (const input of messages) {
    const res = await langWire.chat(input);

    console.log("Assistant:", res.message);

    if (res.correction) {
      console.log("Correction:", res.correction);
    }
  }

  console.log("Word summary:", langWire.getWordSummary());
}

run().catch(console.error);

Create a .env file:

ANTHROPIC_API_KEY=your_api_key_here

API Reference

LangWireConfig

Configuration object accepted by new LangWire(config):

| Field | Type | Required | Description | | --- | --- | --- | --- | | targetLang | string | Yes | Language used by the assistant when replying. | | nativeLang | string | Yes | User's native language used for correction explanations. | | level | 'A1' \| 'A2' \| 'B1' \| 'B2' \| 'C1' \| 'C2' | Yes | CEFR level used to control vocabulary and grammar complexity. | | scenario | string | No | Optional conversation context such as cafe or job_interview. | | apiKey | string | Yes | Anthropic API key used by the adapter. |

chat(userMessage)

chat(userMessage: string): Promise<ChatResponse>

Sends a user message to the model and returns structured JSON output.

ChatResponse shape:

interface ChatResponse {
  message: string;
  correction?: {
    original: string;
    fixed: string;
    explanation: string;
  };
  newWords: string[];
  encouragement?: string;
  hint?: string;
}

Behavior:

• Appends the user message to conversation history.
• Sends full history plus system prompt to the model.
• Parses and validates JSON response.
• Tracks returned vocabulary in the word tracker.
• Appends assistant message to conversation history.
• Adds an optional native-language hint when the learner appears stuck.

getStats()

getStats(): {
  totalMessages: number;
  totalCorrections: number;
  accuracyRate: number;
  mostCommonMistake: string;
}

Returns conversation learning metrics:

• totalMessages: Number of user messages sent.
• totalCorrections: Number of responses that included a correction.
• accuracyRate: Percentage of messages without correction.
• mostCommonMistake: Most frequently repeated correction explanation.

setLevel(level)

setLevel(level: "A1" | "A2" | "B1" | "B2" | "C1" | "C2"): void

Updates CEFR level during an active conversation and rebuilds the system prompt.

exportConversation()

exportConversation(): string

Exports current conversation history, stats, and tracked words as a JSON string.

importConversation(serialized)

importConversation(serialized: string): void

Imports a previously exported JSON snapshot and restores history + stats + words.

getWordSummary()

getWordSummary(): string

Returns a readable summary of tracked vocabulary, for example:

15 words learned, top words: hello, coffee, please

resetConversation()

resetConversation(): void

Clears only chat history. Vocabulary tracking is preserved.

Auto Difficulty Adjustment

If the last 3 assistant replies contain no correction, LangWire suggests moving to the next CEFR level using hint in the user's native language.

Supported Languages and CEFR Levels

| Item | Support | | --- | --- | | Target language | Any language supported by Claude (recommended: EN, TR, ES, FR, DE, IT, PT, JA, KO, ZH) | | Native language for corrections | Any language supported by Claude | | CEFR levels | A1, A2, B1, B2, C1, C2 |

Supported Scenarios

• cafe
• airport
• job_interview
• shopping
• daily_chat

If no scenario is provided, LangWire uses a general daily-conversation context.

Contributing

Contributions are welcome.

Repository: https://github.com/v1onues/langwire

1. Fork the repository.
2. Create a feature branch.
3. Add or update tests for your changes.
4. Run checks:
   • npm run build
   • npm test
5. Open a pull request with a clear description.

MIT License

This project is released under the MIT License.

Links

• npm: https://www.npmjs.com/package/langwire
• GitHub: https://github.com/v1onues/langwire
• Demo Folder: https://github.com/v1onues/langwire/tree/main/demo
• Vercel: https://langwire.vercel.app