vakforge 0.0.1__py3-none-any.whl

vakforge/__init__.py

@@ -0,0 +1,3 @@
+"""vakforge: turn the data your company already has into a self-hosted voice assistant."""
+
+__version__ = "0.0.1"

vakforge/cli.py

@@ -0,0 +1,124 @@
+"""vakforge CLI. Thin: each subcommand delegates to a module."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from vakforge import __version__
+
+app = typer.Typer(
+    help="Turn the data your company already has into a self-hosted voice assistant.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+console = Console()
+err_console = Console(stderr=True)
+
+PROJECT_GITIGNORE = """# written by `vakforge init`
+data/raw/
+runs/
+.venv/
+*.wav
+*.mp3
+*.flac
+*.safetensors
+*.bin
+*.pt
+*.gguf
+"""
+
+
+def _version(value: bool) -> None:
+    if value:
+        console.print(f"vakforge {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool, typer.Option("--version", callback=_version, is_eager=True, help="Show version.")
+    ] = False,
+) -> None:
+    """vakforge."""
+
+
+@app.command()
+def init(
+    name: Annotated[str, typer.Argument(help="Project directory to create.")],
+    locale: Annotated[
+        list[str], typer.Option("--locale", "-l", help="Locale pack id(s), e.g. en-US.")
+    ],
+) -> None:
+    """Scaffold a project folder with a locale."""
+    from vakforge.config import ProjectConfig
+    from vakforge.locales import get_pack, list_packs
+
+    for pack_id in locale:
+        try:
+            get_pack(pack_id)
+        except KeyError:
+            err_console.print(f"[red]unknown locale {pack_id!r}[/]; known: {list_packs()}")
+            raise typer.Exit(2) from None
+
+    project = Path(name)
+    if project.exists() and any(project.iterdir()):
+        err_console.print(f"[red]{project} exists and is not empty[/]")
+        raise typer.Exit(2)
+    for sub in ("data/raw", "data/audio", "configs", "runs"):
+        (project / sub).mkdir(parents=True, exist_ok=True)
+    (project / ".gitignore").write_text(PROJECT_GITIGNORE, encoding="utf-8")
+    cfg_path = ProjectConfig(name=project.name, locales=locale).save(project)
+    console.print(f"[green]created[/] {project}/  ({cfg_path.name}: locales={locale})")
+    console.print(
+        "next: drop your documents, tables, chats or audio into data/raw/ and run "
+        f"`vakforge inspect {project}/data/raw`"
+    )
+
+
+@app.command()
+def validate(
+    manifest: Annotated[Path, typer.Argument(exists=True, dir_okay=False, readable=True)],
+    allow_unconsented: Annotated[
+        bool, typer.Option(help="Accept rows with meta.consent='none' (never exported).")
+    ] = False,
+) -> None:
+    """Validate a canonical `vakforge.jsonl` manifest."""
+    from vakforge.validate import validate_manifest
+
+    convs, issues = validate_manifest(manifest, allow_unconsented=allow_unconsented)
+    if allow_unconsented and any(c.meta.consent == "none" for c in convs):
+        err_console.print(
+            "[yellow]warning:[/] unconsented rows accepted; they will never be exported"
+        )
+    for issue in issues:
+        err_console.print(f"[red]✗[/] {issue}")
+    n_ok = len(convs) - len({i.conv_id for i in issues})
+    console.print(f"{len(convs)} conversation(s) parsed, {n_ok} clean, {len(issues)} issue(s)")
+    raise typer.Exit(1 if issues else 0)
+
+
+@app.command()
+def schema(
+    out: Annotated[
+        Path | None, typer.Option("--out", "-o", help="Write JSON Schema here instead of stdout.")
+    ] = None,
+) -> None:
+    """Export the canonical JSON Schema."""
+    from vakforge.schema import json_schema
+
+    text = json.dumps(json_schema(), indent=2)
+    if out:
+        out.write_text(text + "\n", encoding="utf-8")
+        console.print(f"[green]wrote[/] {out}")
+    else:
+        print(text)
+
+
+if __name__ == "__main__":
+    app()

vakforge/config.py

@@ -0,0 +1,28 @@
+"""Project config (`vakforge.yaml`), written by `init` and read by every stage."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field
+
+CONFIG_NAME = "vakforge.yaml"
+
+
+class ProjectConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    locales: list[str] = Field(min_length=1)
+    data_dir: str = "data"
+
+    @classmethod
+    def load(cls, project_dir: Path) -> ProjectConfig:
+        text = (project_dir / CONFIG_NAME).read_text(encoding="utf-8")
+        return cls.model_validate(yaml.safe_load(text) or {})
+
+    def save(self, project_dir: Path) -> Path:
+        path = project_dir / CONFIG_NAME
+        path.write_text(yaml.safe_dump(self.model_dump(), sort_keys=False), encoding="utf-8")
+        return path

vakforge/locales/__init__.py

@@ -0,0 +1,6 @@
+"""Locale pack registry. Importing this package registers every shipped pack."""
+
+from vakforge.locales import en  # noqa: F401  (registers packs on import)
+from vakforge.locales.base import LocalePack, get_pack, list_packs, register
+
+__all__ = ["LocalePack", "get_pack", "list_packs", "register"]

vakforge/locales/base.py

@@ -0,0 +1,56 @@
+"""LocalePack base and registry. Everything language- or market-specific lives in a pack.
+
+Phase 0 ships the skeleton: identity, language tags, inheritance, and the two text hooks
+core needs for validation and WER. Formats, PII patterns, generators and recipe support
+land in Phase 1 (docs/LOCALE_PACKS.md).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import ClassVar
+
+_PUNCT = re.compile(r"[^\w\s]", re.UNICODE)
+
+
+class LocalePack:
+    """Subclass and set the class attributes. Register with `register()`."""
+
+    id: ClassVar[str]
+    languages: ClassVar[list[str]]
+    parent: ClassVar[str | None] = None
+
+    def all_languages(self) -> set[str]:
+        """Tags this pack accepts on a turn, including inherited ones."""
+        langs = set(self.languages)
+        if self.parent:
+            langs |= get_pack(self.parent).all_languages()
+        return langs
+
+    def detect_lang(self, text: str) -> str:
+        """Per-turn language tag. Default: the pack's first language."""
+        return self.languages[0]
+
+    def normalize_text(self, text: str) -> str:
+        """Text normalization for WER. Default: lowercase, strip punctuation, collapse spaces."""
+        return " ".join(_PUNCT.sub(" ", text.lower()).split())
+
+
+_REGISTRY: dict[str, LocalePack] = {}
+
+
+def register(cls: type[LocalePack]) -> type[LocalePack]:
+    """Class decorator: instantiate and register a pack by id."""
+    _REGISTRY[cls.id] = cls()
+    return cls
+
+
+def get_pack(pack_id: str) -> LocalePack:
+    try:
+        return _REGISTRY[pack_id]
+    except KeyError:
+        raise KeyError(f"unknown locale pack {pack_id!r}; known: {sorted(_REGISTRY)}") from None
+
+
+def list_packs() -> list[str]:
+    return sorted(_REGISTRY)

vakforge/locales/en.py

@@ -0,0 +1,36 @@
+"""English packs: `en` parent plus en-US, en-GB, en-IN.
+
+Phase 0 skeletons. Formats, PII patterns, consent notes and generators come in Phase 1;
+split each into its own package when it grows past a screen.
+"""
+
+from __future__ import annotations
+
+from vakforge.locales.base import LocalePack, register
+
+
+@register
+class En(LocalePack):
+    id = "en"
+    languages = ["en"]
+
+
+@register
+class EnUS(LocalePack):
+    id = "en-US"
+    languages = ["en-US"]
+    parent = "en"
+
+
+@register
+class EnGB(LocalePack):
+    id = "en-GB"
+    languages = ["en-GB"]
+    parent = "en"
+
+
+@register
+class EnIN(LocalePack):
+    id = "en-IN"
+    languages = ["en-IN"]
+    parent = "en"

vakforge/schema.py

@@ -0,0 +1,189 @@
+"""Canonical dataset schema (`vakforge.jsonl`). Source of truth for docs/DATA_FORMAT.md.
+
+Structural rules that need only the record itself live here as pydantic validators.
+Rules that need the filesystem or the locale registry live in `vakforge.validate`.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+SCHEMA_VERSION = "0.1"
+
+Speaker = Literal["user", "agent", "tool"]
+Condition = Literal["studio", "clean", "phone", "noisy"]
+Source = Literal["real", "synthetic", "public"]
+Consent = Literal["recorded_verbal", "written", "synthetic", "public_license", "none"]
+Split = Literal["train", "val", "test"]
+
+
+class _Strict(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class Audio(_Strict):
+    path: str
+    sample_rate: int = 24000
+    channels: int = Field(ge=1, le=2)
+    channel_map: dict[str, Speaker] | None = None
+    duration_s: float = Field(ge=0)
+    condition: Condition = "clean"
+
+    @model_validator(mode="after")
+    def _channel_map_matches(self) -> Audio:
+        if self.channels == 2 and self.channel_map is None:
+            raise ValueError("stereo audio needs channel_map, e.g. {'0': 'user', '1': 'agent'}")
+        if self.channel_map is not None and set(self.channel_map) != {
+            str(i) for i in range(self.channels)
+        }:
+            raise ValueError(f"channel_map keys must be {[str(i) for i in range(self.channels)]}")
+        return self
+
+
+class Language(_Strict):
+    primary: str
+    mix: list[str] = Field(default_factory=list)
+
+
+class Tool(_Strict):
+    name: str
+    description: str = ""
+    parameters: dict[str, Any] = Field(default_factory=lambda: {"type": "object"})
+
+
+class ToolCall(_Strict):
+    id: str
+    name: str
+    arguments: dict[str, Any] = Field(default_factory=dict)
+
+
+class ToolResult(_Strict):
+    id: str
+    content: dict[str, Any] = Field(default_factory=dict)
+
+
+class Entity(_Strict):
+    type: str
+    text: str
+    start_char: int | None = None
+    end_char: int | None = None
+    normalized: Any = None
+
+
+class Turn(_Strict):
+    speaker: Speaker
+    start: float = Field(ge=0)
+    end: float = Field(ge=0)
+    text: str | None = None
+    lang: str | None = None
+    entities: list[Entity] = Field(default_factory=list)
+    overlap: bool = False
+    tool_call: ToolCall | None = None
+    tool_result: ToolResult | None = None
+
+    @property
+    def spoken(self) -> bool:
+        return self.tool_call is None and self.tool_result is None
+
+    @model_validator(mode="after")
+    def _shape(self) -> Turn:
+        if self.end < self.start:
+            raise ValueError(f"end ({self.end}) < start ({self.start})")
+        if self.tool_call and self.tool_result:
+            raise ValueError("a turn carries either tool_call or tool_result, not both")
+        if self.tool_call and self.speaker != "agent":
+            raise ValueError("tool_call turns must have speaker='agent'")
+        if self.tool_result and self.speaker != "tool":
+            raise ValueError("tool_result turns must have speaker='tool'")
+        if self.speaker == "tool" and not self.tool_result:
+            raise ValueError("speaker='tool' turns must carry tool_result")
+        if self.spoken:
+            if not self.text:
+                raise ValueError("spoken turns need non-empty text")
+            if not self.lang:
+                raise ValueError("spoken turns need lang (BCP-47, e.g. 'en-US', 'hi-Latn')")
+        return self
+
+
+class Transcription(_Strict):
+    engine: str
+    verified_by_human: bool = False
+
+
+class Diarization(_Strict):
+    engine: str
+    confidence: float = Field(ge=0, le=1, default=1.0)
+
+
+class Meta(_Strict):
+    source: Source
+    consent: Consent
+    consent_ref: str | None = None
+    voice_consent_ref: str | None = None
+    license: str | None = None
+    pii_redacted: bool
+    redaction_log: str | None = None
+    transcription: Transcription | None = None
+    diarization: Diarization | None = None
+    split: Split
+    created: datetime
+
+
+class Conversation(_Strict):
+    """One conversation. Audio is optional: records built from documents, tables or chat
+    logs have no recording until `synth` renders one."""
+
+    id: str
+    schema_version: str = SCHEMA_VERSION
+    audio: Audio | None = None
+    locale: str
+    language: Language
+    domain: str | None = None
+    scenario: str | None = None
+    system_prompt: str | None = None
+    tools: list[Tool] = Field(default_factory=list)
+    turns: list[Turn] = Field(min_length=1)
+    meta: Meta
+
+    @model_validator(mode="after")
+    def _cross_turn_rules(self) -> Conversation:
+        prev_start = -1.0
+        for i, t in enumerate(self.turns):
+            if t.start < prev_start:
+                raise ValueError(f"turns[{i}]: turns must be sorted by start")
+            prev_start = t.start
+
+        tool_names = {t.name for t in self.tools}
+        call_ids: set[str] = set()
+        for i, t in enumerate(self.turns):
+            if t.tool_call:
+                if t.tool_call.id in call_ids:
+                    raise ValueError(f"turns[{i}]: duplicate tool_call id {t.tool_call.id!r}")
+                call_ids.add(t.tool_call.id)
+                if t.tool_call.name not in tool_names:
+                    raise ValueError(
+                        f"turns[{i}]: tool_call {t.tool_call.name!r} not declared in tools"
+                    )
+            if t.tool_result and t.tool_result.id not in call_ids:
+                raise ValueError(
+                    f"turns[{i}]: tool_result references unknown call id {t.tool_result.id!r}"
+                )
+
+        if self.audio and self.turns:
+            last_end = max(t.end for t in self.turns)
+            if last_end > self.audio.duration_s + 0.5:
+                raise ValueError(
+                    f"turns end at {last_end}s but audio.duration_s is {self.audio.duration_s}s"
+                )
+        return self
+
+
+def json_schema() -> dict[str, Any]:
+    """JSON Schema for one `vakforge.jsonl` line, for external validators."""
+    schema = Conversation.model_json_schema()
+    schema["$schema"] = "https://json-schema.org/draft/2020-12/schema"
+    schema["title"] = f"vakforge conversation v{SCHEMA_VERSION}"
+    return schema

vakforge/validate.py

@@ -0,0 +1,226 @@
+"""`vakforge validate`: file-level rules from docs/DATA_FORMAT.md.
+
+Schema-only rules are enforced by `vakforge.schema`; this module adds the checks that need
+the filesystem (audio files), the locale registry, JSON-Schema tool arguments, and splits.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+import jsonschema
+from pydantic import ValidationError
+
+from vakforge.locales import get_pack
+from vakforge.schema import Conversation
+
+
+@dataclass(frozen=True)
+class Issue:
+    conv_id: str
+    field: str
+    message: str
+    fix: str = ""
+    line: int | None = None
+
+    def __str__(self) -> str:
+        where = f"line {self.line} " if self.line else ""
+        s = f"{where}{self.conv_id} · {self.field}: {self.message}"
+        return f"{s}  → {self.fix}" if self.fix else s
+
+
+def _pydantic_issues(conv_id: str, line: int, err: ValidationError) -> list[Issue]:
+    out = []
+    for e in err.errors():
+        loc = ".".join(str(p) for p in e["loc"]) or "<record>"
+        msg = e["msg"].removeprefix("Value error, ")
+        out.append(Issue(conv_id, loc, msg, line=line))
+    return out
+
+
+def _check_audio(conv: Conversation, root: Path, line: int) -> list[Issue]:
+    if conv.audio is None:
+        return []
+    import soundfile as sf  # local import keeps `import vakforge.schema` light
+
+    path = root / conv.audio.path
+    if not path.exists():
+        return [Issue(conv.id, "audio.path", f"{path} does not exist", "fix the path", line)]
+    try:
+        info = sf.info(str(path))
+    except Exception as exc:  # soundfile raises RuntimeError/LibsndfileError
+        return [Issue(conv.id, "audio.path", f"cannot decode: {exc}", "re-encode as WAV", line)]
+    issues = []
+    if info.samplerate != conv.audio.sample_rate:
+        issues.append(
+            Issue(
+                conv.id,
+                "audio.sample_rate",
+                f"declared {conv.audio.sample_rate}, file is {info.samplerate}",
+                "run `vakforge prepare` to resample or fix the declaration",
+                line,
+            )
+        )
+    if info.channels != conv.audio.channels:
+        issues.append(
+            Issue(
+                conv.id,
+                "audio.channels",
+                f"declared {conv.audio.channels}, file has {info.channels}",
+                "fix the declaration or channel_map",
+                line,
+            )
+        )
+    if abs(info.duration - conv.audio.duration_s) > 0.5:
+        issues.append(
+            Issue(
+                conv.id,
+                "audio.duration_s",
+                f"declared {conv.audio.duration_s}, file is {info.duration:.2f}",
+                "set duration_s from the file",
+                line,
+            )
+        )
+    return issues
+
+
+def _check_locale(conv: Conversation, line: int) -> list[Issue]:
+    try:
+        pack = get_pack(conv.locale)
+    except KeyError as exc:
+        return [Issue(conv.id, "locale", str(exc), "use a registered pack id", line)]
+    allowed = pack.all_languages()
+    return [
+        Issue(
+            conv.id,
+            f"turns[{i}].lang",
+            f"{t.lang!r} is not declared by pack {conv.locale!r} (allowed: {sorted(allowed)})",
+            "tag the turn with a language the pack declares, or pick another locale",
+            line,
+        )
+        for i, t in enumerate(conv.turns)
+        if t.lang and t.lang not in allowed
+    ]
+
+
+def _check_tools(conv: Conversation, line: int) -> list[Issue]:
+    issues = []
+    schemas = {}
+    for i, tool in enumerate(conv.tools):
+        try:
+            jsonschema.Draft202012Validator.check_schema(tool.parameters)
+            schemas[tool.name] = jsonschema.Draft202012Validator(tool.parameters)
+        except jsonschema.SchemaError as exc:
+            issues.append(
+                Issue(
+                    conv.id,
+                    f"tools[{i}].parameters",
+                    f"invalid JSON Schema: {exc.message}",
+                    "fix the parameters schema",
+                    line,
+                )
+            )
+    for i, t in enumerate(conv.turns):
+        if t.tool_call and (v := schemas.get(t.tool_call.name)):
+            for err in v.iter_errors(t.tool_call.arguments):
+                issues.append(
+                    Issue(
+                        conv.id,
+                        f"turns[{i}].tool_call.arguments",
+                        err.message,
+                        "make the arguments match tools[].parameters",
+                        line,
+                    )
+                )
+    return issues
+
+
+def _check_consent(conv: Conversation, line: int, allow_unconsented: bool) -> list[Issue]:
+    if conv.meta.consent == "none" and not allow_unconsented:
+        return [
+            Issue(
+                conv.id,
+                "meta.consent",
+                "consent is 'none'",
+                "record a consent basis, or pass --allow-unconsented (row stays unexportable)",
+                line,
+            )
+        ]
+    return []
+
+
+def _check_splits(convs: list[Conversation], root: Path) -> list[Issue]:
+    """`splits.json`, when present, must agree with meta.split and cover every id."""
+    path = root / "splits.json"
+    if not path.exists():
+        return []
+    try:
+        splits: dict[str, list[str]] = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        return [Issue("<splits.json>", "splits.json", f"invalid JSON: {exc}", "fix the file")]
+    assigned: dict[str, str] = {}
+    issues = []
+    for split, ids in splits.items():
+        if split == "seed":
+            continue
+        for cid in ids:
+            if cid in assigned:
+                issues.append(
+                    Issue(cid, "splits.json", f"in both {assigned[cid]} and {split}", "keep one")
+                )
+            assigned[cid] = split
+    for c in convs:
+        if c.id not in assigned:
+            issues.append(Issue(c.id, "splits.json", "not assigned to any split", "add it"))
+        elif assigned[c.id] != c.meta.split:
+            issues.append(
+                Issue(
+                    c.id,
+                    "meta.split",
+                    f"row says {c.meta.split!r}, splits.json says {assigned[c.id]!r}",
+                    "make them agree",
+                )
+            )
+    return issues
+
+
+def validate_manifest(
+    manifest: Path, *, allow_unconsented: bool = False
+) -> tuple[list[Conversation], list[Issue]]:
+    """Validate a `vakforge.jsonl`. Returns the parsed conversations and every issue found.
+
+    Audio paths resolve relative to the manifest's directory, per docs/DATA_FORMAT.md.
+    """
+    root = manifest.parent
+    convs: list[Conversation] = []
+    issues: list[Issue] = []
+    seen_ids: set[str] = set()
+
+    with manifest.open(encoding="utf-8") as fh:
+        for line_no, raw in enumerate(fh, start=1):
+            if not raw.strip():
+                continue
+            try:
+                data = json.loads(raw)
+            except json.JSONDecodeError as exc:
+                issues.append(Issue("<unparsed>", "json", str(exc), "fix the JSON", line_no))
+                continue
+            conv_id = str(data.get("id", "<no id>")) if isinstance(data, dict) else "<no id>"
+            try:
+                conv = Conversation.model_validate(data)
+            except ValidationError as exc:
+                issues.extend(_pydantic_issues(conv_id, line_no, exc))
+                continue
+            if conv.id in seen_ids:
+                issues.append(Issue(conv.id, "id", "duplicate id", "ids must be unique", line_no))
+            seen_ids.add(conv.id)
+            convs.append(conv)
+            issues += _check_audio(conv, root, line_no)
+            issues += _check_locale(conv, line_no)
+            issues += _check_tools(conv, line_no)
+            issues += _check_consent(conv, line_no, allow_unconsented)
+
+    issues += _check_splits(convs, root)
+    return convs, issues

vakforge-0.0.1.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: vakforge
+Version: 0.0.1
+Summary: Turn the data your company already has into a self-hosted, real-time voice assistant.
+Project-URL: Homepage, https://github.com/vakforge-ai/vakforge
+Project-URL: Repository, https://github.com/vakforge-ai/vakforge
+Author-email: vakforge <vakforge.ai@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: fine-tuning,locale,realtime,speech-to-speech,voice-agent
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.11
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6
+Requires-Dist: rich>=13
+Requires-Dist: soundfile>=0.12
+Requires-Dist: typer>=0.12
+Provides-Extra: cascade
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: lfm25
+Provides-Extra: moshi
+Provides-Extra: qwen
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/vakforge-ai/vakforge/main/site/assets/social/readme-banner.webp" alt="vakforge: your data, your voice assistant, your hardware" width="100%">
+</p>
+
+# vakforge
+
+**Turn the data your company already has into a self-hosted, real-time voice assistant.**
+
+Documents, FAQs, database tables, chat logs, CRM records, recorded calls: vakforge works out what your assistant actually needs (knowledge, behaviour, tools, voice, language), generates the conversational data you lack, trains only what needs training, proves the result beats the base model on your own held-out data, and serves it on your hardware behind protocols your clients already speak, starting with the OpenAI Realtime WebSocket format. Open models only, nothing calls a hosted API, any language through locale packs. Launch locales: English (US, UK, India) and Hinglish.
+
+> Status: pre-alpha. See [`docs/ROADMAP.md`](docs/ROADMAP.md) for what exists today.
+
+## The problem
+
+Open speech-to-speech models exist (Moshi, PersonaPlex, LFM2.5-Audio, Qwen-Omni). Fine-tuning scripts exist for some of them. Evaluation tools exist. Serving frameworks exist. What does not exist is one path from *"here is what my company knows"* to *"here is a voice assistant that handles my workflow, I can prove it is better than the base model, and my existing voice client can talk to it without a rewrite."* Every team rebuilds that path badly, and most of them fine-tune when they should have used retrieval.
+
+## What ships
+
+vakforge is three things in one repo:
+
+1. **A core library and CLI** (`pip install vakforge`). Zero ML dependencies. Canonical dataset schema, validator, data inspector, decision engine, locale packs. Runs on a laptop.
+2. **An agent skill** (`skill/`). Drop it into Claude Code or any coding agent. The agent reads your data, runs the decision guide, writes the recipe-specific glue for your project, and verifies every upstream API against source before using it. The knowledge lives here; the glue code is generated per project.
+3. **Recipes** (`docs/RECIPES.md`). Tested paths from base model to served assistant. Each is an optional extra, isolated because model libraries conflict. Only recipes run end to end get listed.
+
+```
+vakforge inspect ./data        ->  what is actually in your documents, tables, chats, audio
+vakforge recommend             ->  what needs customizing (often: retrieval, not the model)
+vakforge prepare               ->  ingest, transcribe, redact PII, canonical dataset
+vakforge synth                 ->  synthetic dialogues in your locale over your tools and facts
+vakforge train --recipe X      ->  one tested recipe, not a menu of 400 models
+vakforge eval                  ->  base vs tuned: WER, entities, tool calls, latency, voice
+vakforge serve                 ->  your open model behind the Realtime protocol; WebRTC and SIP next
+```
+
+## Bring any data
+
+| You have | vakforge does |
+|---|---|
+| Documents, FAQs, SOPs, knowledge base | Retrieval at inference. Facts stay out of weights. Synthetic dialogues grounded in them. |
+| Database tables, CRM, product catalogue | Tool definitions over your data, synthetic dialogues that exercise every tool, behaviour fine-tune for reliable tool use. |
+| Chat logs, transcripts | Behaviour and workflow fine-tune of the language component; rendered to audio via `synth`. |
+| Recorded calls (mono or stereo) | Transcribe, diarize, redact, then everything above plus voice, timing and full-duplex recipes. |
+| Nothing yet | Scenario templates in your locale, rendered with open TTS, so you can ship a v0 and collect real data. |
+
+## Locale packs
+
+The pipeline is language-agnostic. Everything language- or market-specific lives in a locale pack: number/currency/date/address formats, PII patterns, privacy-law notes, name generators for synthetic data, preferred models, and a benchmark. See [`docs/LOCALE_PACKS.md`](docs/LOCALE_PACKS.md).
+
+| Pack | Covers | Speech output today | Status |
+|---|---|---|---|
+| `en` | en-US, en-GB, en-IN | native (all recipes) | launch |
+| `hi-Latn` | Hinglish / Roman Hindi, Hindi-English code-switching | English output; Hindi via cascade | launch, the hard-case showcase |
+| `zh-CN` | Mandarin | via `qwen-omni` | planned |
+| `es`, `de`, `fr`, `pt-BR`, `ja`, `ar` | | via `qwen-omni` or cascade | planned, contributions welcome |
+
+## Recipes
+
+| Recipe | Base model | Good for | Duplex | Hardware (train) | Status |
+|---|---|---|---|---|---|
+| `lfm25-audio` | LiquidAI LFM2.5-Audio-1.5B | workflow, tool use, style, CPU deploy | turn-based | 1x 24 GB GPU | planned (first) |
+| `moshi-lora` | Kyutai Moshi / NVIDIA PersonaPlex | interruptions, natural timing, persona | full-duplex | 1x 40-80 GB GPU | planned |
+| `qwen-omni` | Qwen3-Omni | multilingual incl. Mandarin, function calling | near-duplex | 80 GB / multi-GPU | planned |
+| `cascade` | STT + LLM LoRA + TTS chosen by locale | any language with a good STT+TTS pair | turn-based | 1x 24 GB GPU | planned |
+
+Details in [`docs/RECIPES.md`](docs/RECIPES.md).
+
+## Serving: open models, standard protocols
+
+"OpenAI Realtime compatible" describes the wire format, not the model. Every recipe serves an open model on your hardware; nothing calls OpenAI or any hosted API. We speak the Realtime WebSocket format first because it is the closest thing voice agents have to a common protocol: teams already on GPT Realtime change one URL, and Pipecat, LiveKit and Twilio integrations work unchanged. Open speech-to-speech models each ship their own ad-hoc protocol, so copying a widely used shape beats inventing another.
+
+The server separates the model backend from the protocol, so more front ends plug in without touching recipes:
+
+| Protocol | For | Status |
+|---|---|---|
+| OpenAI Realtime WebSocket (documented subset) | teams migrating off GPT Realtime; Pipecat, LiveKit, Twilio clients | first |
+| WebRTC via LiveKit or Pipecat transports | browser and mobile apps, lowest latency | next |
+| SIP / telephony | call centres and phone lines | next |
+| Plain HTTP, one turn per request | batch jobs, simple integrations | planned |
+| Gemini Live API format | teams on Google's stack | on request |
+
+## Why launch with English and Hinglish
+
+English is where the strongest open speech-to-speech models are, so every recipe works out of the box for US, UK and Indian English. Hinglish is the stress test: code-switching, Roman vs Devanagari script, Indian names and rupee amounts, noisy phone lines. If the pipeline handles that, a new locale pack is mostly formats and models, not new architecture.
+
+## Quick start (target UX, not all steps implemented yet)
+
+```bash
+uv sync
+uv run vakforge init my-assistant --locale en-US && cd my-assistant
+uv run vakforge inspect ./data
+uv run vakforge recommend
+```
+
+## Documentation
+
+- [`docs/DECISION_GUIDE.md`](docs/DECISION_GUIDE.md): what actually needs customizing; when not to fine-tune
+- [`docs/LOCALE_PACKS.md`](docs/LOCALE_PACKS.md): what a locale pack contains; how to add one
+- [`docs/DATA_FORMAT.md`](docs/DATA_FORMAT.md): canonical dataset schema
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md): package layout
+- [`docs/RECIPES.md`](docs/RECIPES.md): per-model training recipes
+- [`docs/EVALUATION.md`](docs/EVALUATION.md): metrics, report format, per-locale benchmarks
+- [`docs/DATA_ETHICS.md`](docs/DATA_ETHICS.md): consent, PII, licences, privacy law by region
+- [`docs/ROADMAP.md`](docs/ROADMAP.md): status
+- [`CONTRIBUTING.md`](CONTRIBUTING.md)
+
+## Related projects (we build on these, not against them)
+
+Unsloth, LLaMA-Factory, ms-swift, kyutai-labs/moshi-finetune, NVIDIA PersonaPlex, liquid-audio, Qwen-Omni, Pipecat, LiveKit Agents, vLLM-omni, UltraEval-Audio, AI4Bharat, Common Voice
+
+## Licence
+
+Apache-2.0 for this code. Each recipe's base model has its own licence, see `docs/RECIPES.md`. Datasets you create with vakforge are yours; the consent metadata we require is there to keep it that way.

vakforge-0.0.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+vakforge/__init__.py,sha256=5h9Ii_gTeHNgUtGEmpnWp265KGKbEd6IId5AJA5lB6o,114
+vakforge/cli.py,sha256=0IwEmnxwtEpqfRLHeHKThUofFJXWxTQi-8n7FSC1n3c,3667
+vakforge/config.py,sha256=PSNJnKkFyWeqHAkSHtfghIzKWHlHjfhOOcT6sHB7Z_Y,815
+vakforge/schema.py,sha256=M5-U03o03fBJ95p32NuMajf5RMIgCCL8FMYX1BqYWGU,6277
+vakforge/validate.py,sha256=zKMGive36ixTk1vzMc0Dy944zzLRgKxYTOMdL-pktRI,7965
+vakforge/locales/__init__.py,sha256=ZZSOQQh6N7HKIBXlCY-gUnKunBC4Wm2rTooWm1Fpl5c,298
+vakforge/locales/base.py,sha256=kqLMp3LgW3ooMu_QRH5vUDDySVEOhyPMyruX7iRE8ys,1722
+vakforge/locales/en.py,sha256=CZ_Zl3VFUJGNezFXOHubcSy26Mw5b5rOu1A9qZnfTP0,664
+vakforge-0.0.1.dist-info/METADATA,sha256=E0o03pfq6lojnC50H5-v2CeyvZTM6-hRDT62kbYgSoY,9151
+vakforge-0.0.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+vakforge-0.0.1.dist-info/entry_points.txt,sha256=jYQ3xAhnUbJesULZn-Y8OVVJzVmdiAe9ueHTXaZQKgc,46
+vakforge-0.0.1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+vakforge-0.0.1.dist-info/RECORD,,

vakforge-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

vakforge-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vakforge = vakforge.cli:app

vakforge-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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 [yyyy] [name of copyright owner]
+
+   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.