kelam-core 0.1.0__tar.gz

kelam_core-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: kelam-core
+Version: 0.1.0
+Summary: Shared Kelam contracts: agent schemas, folder<->record translation, model registry, call metrics.
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pyyaml<7,>=6.0

kelam_core-0.1.0/kelam_core/__init__.py

@@ -0,0 +1,7 @@
+"""kelam-core — the shared contract both the CLI and the backend depend on.
+
+Pure-python, light deps (pydantic + pyyaml): agent schemas, the agent-folder<->record
+translation used by pull/push, the model registry the linter validates against, and the
+derived call metrics used by export/stats. Keeping these here is what stops the CLI and the
+backend from drifting on the push/pull or metrics contracts.
+"""

kelam_core-0.1.0/kelam_core/metrics.py

@@ -0,0 +1,149 @@
+"""Derived call metrics — pure functions over CallLog dicts.
+
+The CallLog stores what happened (transcript, timestamps, status); these helpers derive
+the numbers an analysis or dashboard wants (turn counts, word counts, talk ratio,
+durations) so every export consumer gets the same definitions. Everything here is pure
+and dependency-free: the service enriches API responses with it, the CLI summarizes
+with it, and tests exercise it without AWS.
+
+Per-turn latency comes from the worker's `turn_metrics` rows (one per user turn:
+eou_delay + llm_ttft + tts_ttfb, seconds); calls recorded before capture existed
+simply have no rows, and every latency metric degrades to None for them.
+"""
+from __future__ import annotations
+
+from collections import Counter
+from datetime import datetime
+
+
+AGENT_ROLES = ("assistant", "agent")
+
+# Flat per-call row for tabular consumers (CSV export). Transcript text is excluded —
+# tables get the numbers, jsonl/json get the full conversation.
+CSV_FIELDS = [
+    "call_id", "agent_id", "workspace", "direction", "status",
+    "from_number", "to_number", "started_at", "ended_at", "duration_seconds",
+    "user_turns", "agent_turns", "tool_calls", "user_words", "agent_words",
+    "agent_talk_ratio", "words_per_minute",
+    "response_latency_p50", "response_latency_p95",
+]
+
+
+def _parse_ts(value) -> datetime | None:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(str(value))
+    except ValueError:
+        return None
+
+
+def _word_count(text: str) -> int:
+    return len((text or "").split())
+
+
+def call_duration_seconds(call: dict) -> float | None:
+    """Stored duration if present, else derived from started_at/ended_at."""
+    if call.get("duration_seconds") is not None:
+        return call["duration_seconds"]
+    started, ended = _parse_ts(call.get("started_at")), _parse_ts(call.get("ended_at"))
+    if started and ended and started.tzinfo == ended.tzinfo:
+        return max((ended - started).total_seconds(), 0.0)
+    return None
+
+
+def turn_latencies(call: dict) -> list[float]:
+    """Per-turn response latency samples (seconds): eou_delay + llm_ttft + tts_ttfb.
+    A turn counts only when the caller actually heard a response (llm_ttft and
+    tts_ttfb both present); eou_delay is added when emitted (it isn't under stt-based
+    turn detection). Empty for calls recorded before the worker captured latency."""
+    samples = []
+    for t in call.get("turn_metrics") or []:
+        if t.get("llm_ttft") is None or t.get("tts_ttfb") is None:
+            continue
+        samples.append((t.get("eou_delay") or 0.0) + t["llm_ttft"] + t["tts_ttfb"])
+    return samples
+
+
+def call_metrics(call: dict) -> dict:
+    """Per-call derived metrics. Tool segments come in pairs ("→ called f(...)" then
+    "← f returned: ..."); tool_calls counts invocations, not segments."""
+    transcript = call.get("transcript") or []
+    user = [s for s in transcript if s.get("role") == "user"]
+    agent = [s for s in transcript if s.get("role") in AGENT_ROLES]
+    tool_calls = sum(1 for s in transcript
+                     if s.get("role") == "tool" and (s.get("text") or "").startswith("→"))
+    user_words = sum(_word_count(s.get("text", "")) for s in user)
+    agent_words = sum(_word_count(s.get("text", "")) for s in agent)
+    spoken = user_words + agent_words
+    duration = call_duration_seconds(call)
+    latencies = sorted(turn_latencies(call))
+    return {
+        "duration_seconds": duration,
+        "user_turns": len(user),
+        "agent_turns": len(agent),
+        "tool_calls": tool_calls,
+        "user_words": user_words,
+        "agent_words": agent_words,
+        "agent_talk_ratio": round(agent_words / spoken, 3) if spoken else None,
+        "words_per_minute": round(spoken / (duration / 60), 1) if duration else None,
+        "response_latency_p50": round(_percentile(latencies, 50), 3) if latencies else None,
+        "response_latency_p95": round(_percentile(latencies, 95), 3) if latencies else None,
+    }
+
+
+def with_metrics(call: dict) -> dict:
+    """The call dict plus a `metrics` sub-dict (the export enrichment)."""
+    return {**call, "metrics": call_metrics(call)}
+
+
+def flatten_call(call: dict) -> dict:
+    """One flat row (CSV_FIELDS) per call; metrics inlined, transcript dropped."""
+    m = call.get("metrics") or call_metrics(call)
+    row = {k: call.get(k) for k in CSV_FIELDS if k in call}
+    row.update({k: m[k] for k in m if k in CSV_FIELDS})
+    return {k: row.get(k) for k in CSV_FIELDS}
+
+
+def _percentile(sorted_values: list[float], p: float) -> float:
+    """Nearest-rank percentile on an already-sorted list (small-N friendly)."""
+    if not sorted_values:
+        return 0.0
+    idx = min(int(round(p / 100 * (len(sorted_values) - 1))), len(sorted_values) - 1)
+    return sorted_values[idx]
+
+
+def summarize(calls: list[dict]) -> dict:
+    """Aggregate stats over a set of calls — what `kelam stats` prints."""
+    metrics = [call_metrics(c) for c in calls]
+    durations = sorted(m["duration_seconds"] for m in metrics
+                       if m["duration_seconds"] is not None)
+    latencies = sorted(s for c in calls for s in turn_latencies(c))
+    started = sorted(c.get("started_at") for c in calls if c.get("started_at"))
+    return {
+        "calls": len(calls),
+        "by_status": dict(Counter(c.get("status", "?") for c in calls)),
+        "by_direction": dict(Counter(c.get("direction", "?") for c in calls)),
+        "by_agent": dict(Counter(c.get("agent_id", "?") for c in calls)),
+        "first_call": started[0] if started else None,
+        "last_call": started[-1] if started else None,
+        "duration_seconds": {
+            "total": round(sum(durations), 1),
+            "avg": round(sum(durations) / len(durations), 1) if durations else None,
+            "p50": _percentile(durations, 50) if durations else None,
+            "p95": _percentile(durations, 95) if durations else None,
+            "max": durations[-1] if durations else None,
+        },
+        "turns": {
+            "user": sum(m["user_turns"] for m in metrics),
+            "agent": sum(m["agent_turns"] for m in metrics),
+            "tool_calls": sum(m["tool_calls"] for m in metrics),
+        },
+        # Pooled per-turn response latency (EOU -> first agent audio) across all calls;
+        # turns_measured is 0 (and percentiles None) when no call has latency capture.
+        "response_latency_seconds": {
+            "turns_measured": len(latencies),
+            "p50": round(_percentile(latencies, 50), 3) if latencies else None,
+            "p95": round(_percentile(latencies, 95), 3) if latencies else None,
+        },
+    }

kelam_core-0.1.0/kelam_core/registry.py

@@ -0,0 +1,134 @@
+"""Curated registry of supported models — the single source of truth.
+
+The linter validates agent.yaml against this, and (later) the CLI surfaces it.
+Adding a model to an existing provider = one entry here. Adding a NEW LLM provider
+also needs a branch in the worker's `_build_llm` (the two are kept in sync by tests).
+LLM ids are LiteLLM-style `provider/model`; STT/TTS ids map to LiveKit plugin classes.
+"""
+from __future__ import annotations
+
+LLM_MODELS: dict[str, str] = {
+    "anthropic/claude-haiku-4-5": "Fastest, lowest latency — default for voice",
+    "anthropic/claude-sonnet-4-6": "Balanced quality and speed",
+    "anthropic/claude-opus-4-8": "Most capable, highest latency",
+    "openai/gpt-4o": "OpenAI flagship — strong quality",
+    "openai/gpt-4o-mini": "OpenAI small — fast and cheap",
+}
+
+STT_MODELS: dict[str, str] = {
+    "deepgram/nova-3": "Recommended",
+    "deepgram/nova-2": "Older, still fine",
+}
+
+TTS_MODELS: dict[str, str] = {
+    "elevenlabs/eleven_flash_v2_5": "Lowest latency",
+    "elevenlabs/eleven_turbo_v2_5": "Low latency, a bit richer — default",
+    "elevenlabs/eleven_multilingual_v2": "Best quality, higher latency",
+}
+
+TURN_DETECTION: dict[str, str] = {
+    "vad": "Fastest, silence-based (default)",
+    "model": "Most accurate, LiveKit's audio turn detector (reads the caller's audio)",
+    "stt": "Uses the transcriber's end-of-speech signal",
+}
+
+# LiveKit enhanced noise cancellation, applied to the caller's audio before STT.
+# Requires LiveKit Cloud transport (we're on it); ids map to plugin classes in the worker.
+NOISE_CANCELLATION: dict[str, str] = {
+    "nc": "Remove environmental noise (traffic, fans, music) — no extra cost (default)",
+    "bvc_telephony": "Also suppress competing background voices, tuned for phone calls — extra cost",
+    "off": "No filtering — pass the raw caller audio through",
+}
+
+DEFAULT_LLM = "anthropic/claude-haiku-4-5"
+DEFAULT_STT = "deepgram/nova-3"
+DEFAULT_TTS = "elevenlabs/eleven_turbo_v2_5"
+DEFAULT_VOICE_ID = "21m00Tcm4TlvDq8ikWAM"  # a known-good ElevenLabs voice
+
+
+# ---- languages ----
+# Source of truth for what the linter accepts. STT codes are BCP-47 as Deepgram documents
+# them (https://developers.deepgram.com/docs/models-languages-overview); "multi" is
+# Deepgram's code-switching mode. TTS codes are the base languages each ElevenLabs model
+# speaks. The LLMs are multilingual, so language support is decided by STT/TTS alone.
+
+_NOVA_2_LANGUAGES = {
+    "multi",  # code-switching (en + es only on nova-2)
+    "bg", "ca", "cs", "da", "da-DK", "de", "de-CH", "el", "et", "fi", "fr", "fr-CA",
+    "hi", "hu", "id", "it", "ja", "ko", "ko-KR", "lt", "lv", "ms", "nl", "nl-BE",
+    "no", "pl", "pt", "pt-BR", "pt-PT", "ro", "ru", "sk", "sv", "sv-SE",
+    "th", "th-TH", "tr", "uk", "vi",
+    "en", "en-AU", "en-GB", "en-IN", "en-NZ", "en-US",
+    "es", "es-419",
+    "zh", "zh-CN", "zh-Hans", "zh-Hant", "zh-HK", "zh-TW",
+}
+
+STT_LANGUAGES: dict[str, set[str]] = {
+    # nova-3 = nova-2's coverage plus the languages below; its "multi" mode
+    # code-switches across en/es/fr/de/hi/ru/pt/ja/it/nl.
+    "deepgram/nova-3": _NOVA_2_LANGUAGES | {
+        "ar", "be", "bn", "bs", "fa", "gu", "gu-IN", "he", "hr", "kn", "mk",
+        "mr", "sl", "sr", "ta", "te", "tl", "ur",
+    },
+    "deepgram/nova-2": _NOVA_2_LANGUAGES,
+}
+
+# Every curated ElevenLabs model is multilingual; v2.5 adds hu/no/vi over multilingual_v2.
+_ELEVEN_V2_LANGUAGES = {
+    "ar", "bg", "cs", "da", "de", "el", "en", "es", "fi", "fil", "fr", "hi", "hr",
+    "id", "it", "ja", "ko", "ms", "nl", "pl", "pt", "ro", "ru", "sk", "sv", "ta",
+    "tr", "uk", "zh",
+}
+
+TTS_LANGUAGES: dict[str, set[str]] = {
+    "elevenlabs/eleven_flash_v2_5": _ELEVEN_V2_LANGUAGES | {"hu", "no", "vi"},
+    "elevenlabs/eleven_turbo_v2_5": _ELEVEN_V2_LANGUAGES | {"hu", "no", "vi"},
+    "elevenlabs/eleven_multilingual_v2": _ELEVEN_V2_LANGUAGES,
+}
+
+# Models that accept an explicit language code at synthesis time (ISO 639, e.g. "es").
+# multilingual_v2 does not — it infers the language from the text.
+TTS_LANGUAGE_ENFORCEABLE = {
+    "elevenlabs/eleven_flash_v2_5",
+    "elevenlabs/eleven_turbo_v2_5",
+}
+
+# Providers don't agree on every base code (Deepgram says Tagalog, ElevenLabs Filipino).
+_TTS_LANGUAGE_ALIASES = {"tl": "fil"}
+
+# Display names for prompts and linter messages (union of the sets above).
+LANGUAGE_NAMES: dict[str, str] = {
+    "ar": "Arabic", "be": "Belarusian", "bg": "Bulgarian", "bn": "Bengali",
+    "bs": "Bosnian", "ca": "Catalan", "cs": "Czech", "da": "Danish", "de": "German",
+    "el": "Greek", "en": "English", "es": "Spanish", "et": "Estonian", "fa": "Farsi",
+    "fi": "Finnish", "fil": "Filipino", "fr": "French", "gu": "Gujarati", "he": "Hebrew",
+    "hi": "Hindi", "hr": "Croatian", "hu": "Hungarian", "id": "Indonesian",
+    "it": "Italian", "ja": "Japanese", "kn": "Kannada", "ko": "Korean",
+    "lt": "Lithuanian", "lv": "Latvian", "mk": "Macedonian", "mr": "Marathi",
+    "ms": "Malay", "nl": "Dutch", "no": "Norwegian", "pl": "Polish", "pt": "Portuguese",
+    "ro": "Romanian", "ru": "Russian", "sk": "Slovak", "sl": "Slovenian",
+    "sr": "Serbian", "sv": "Swedish", "ta": "Tamil", "te": "Telugu", "th": "Thai",
+    "tl": "Tagalog", "tr": "Turkish", "uk": "Ukrainian", "ur": "Urdu",
+    "vi": "Vietnamese", "zh": "Chinese",
+}
+
+
+def split(model_id: str) -> tuple[str, str]:
+    """`anthropic/claude-haiku-4-5` -> ('anthropic', 'claude-haiku-4-5')."""
+    provider, _, model = model_id.partition("/")
+    return provider, model
+
+
+def base_language(code: str) -> str:
+    """`fr-CA` -> `fr`. The agent-level language and regional STT codes share a base."""
+    return code.partition("-")[0].lower()
+
+
+def tts_language(code: str) -> str:
+    """The ElevenLabs base code for an agent language (handles provider naming splits)."""
+    base = base_language(code)
+    return _TTS_LANGUAGE_ALIASES.get(base, base)
+
+
+def language_name(code: str) -> str:
+    return LANGUAGE_NAMES.get(base_language(code), code)

kelam_core-0.1.0/kelam_core/schemas.py

@@ -0,0 +1,310 @@
+"""Pydantic models for an agent and its call logs.
+
+`AgentConfig` is the `agent.yaml` contract (validated against the model registry).
+Scenarios and tools are stored separately (one record each); see translation.py.
+CallLog requires both transcript and recording_url (a finalized call always has both).
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from kelam_core import registry
+
+
+class LLMConfig(BaseModel):
+    model: str = registry.DEFAULT_LLM
+    temperature: float = Field(0.4, ge=0.0, le=1.0)
+    max_tokens: int = Field(300, ge=64, le=4096)
+
+    @field_validator("model")
+    @classmethod
+    def _known(cls, v: str) -> str:
+        if v not in registry.LLM_MODELS:
+            raise ValueError(f"unknown LLM model {v!r}; choices: {sorted(registry.LLM_MODELS)}")
+        return v
+
+
+class STTConfig(BaseModel):
+    model: str = registry.DEFAULT_STT
+    language: str = "en-US"
+
+    @field_validator("model")
+    @classmethod
+    def _known(cls, v: str) -> str:
+        if v not in registry.STT_MODELS:
+            raise ValueError(f"unknown STT model {v!r}; choices: {sorted(registry.STT_MODELS)}")
+        return v
+
+
+class VoiceSettingsConfig(BaseModel):
+    """ElevenLabs voice tuning, applied only when this block is present (omit it to use the
+    model's defaults). Lower `stability` = more expressive/variable delivery; higher `style`
+    = more emotive; `use_speaker_boost` adds presence. These are what make a stock voice sound
+    natural vs. flat — the defaults are ElevenLabs' own, which read fairly robotic."""
+
+    stability: float = Field(0.5, ge=0.0, le=1.0)
+    similarity_boost: float = Field(0.75, ge=0.0, le=1.0)
+    style: float = Field(0.0, ge=0.0, le=1.0)
+    use_speaker_boost: bool = True
+    speed: float = Field(1.0, ge=0.7, le=1.2)
+
+
+class TTSConfig(BaseModel):
+    model: str = registry.DEFAULT_TTS
+    voice_id: str = registry.DEFAULT_VOICE_ID
+    # Optional ElevenLabs voice tuning; None = the model's default settings.
+    voice_settings: VoiceSettingsConfig | None = None
+
+    @field_validator("model")
+    @classmethod
+    def _known(cls, v: str) -> str:
+        if v not in registry.TTS_MODELS:
+            raise ValueError(f"unknown TTS model {v!r}; choices: {sorted(registry.TTS_MODELS)}")
+        return v
+
+
+class TurnConfig(BaseModel):
+    detection: Literal["vad", "model", "stt"] = "vad"
+    endpointing_min_ms: int = Field(500, ge=0, le=5000)
+    preemptive_generation: bool = True
+    interruptible: bool = True
+    # Guard against false barge-in from background noise. min_interruption_words requires at
+    # least this many *transcribed* words before the caller is treated as interrupting — at 1
+    # (default) a cough or TV (no real words) no longer cuts the agent off, but a real
+    # "stop"/"wait" still does; set 0 for hair-trigger barge-in. min_interruption_ms is the
+    # minimum speech duration to count. Pairs with the noise_cancellation knob.
+    min_interruption_words: int = Field(1, ge=0, le=10)
+    min_interruption_ms: int = Field(500, ge=0, le=5000)
+
+
+class GreetingConfig(BaseModel):
+    # Spoken live at call start. Empty = wait for the caller to speak first.
+    text: str = ""
+
+
+class PhoneConfig(BaseModel):
+    # Intent only. The assigned number(s) are server-managed (see AgentRecord).
+    inbound: bool = True
+    outbound: bool = True
+
+
+class EndCallConfig(BaseModel):
+    """Opt-in: let the agent hang up the call itself once it decides the conversation is
+    done. Maps onto LiveKit's prebuilt EndCallTool (an `end_call` function tool the LLM can
+    invoke). Default off — an agent with no `end_call` block, or `enabled: false`, never
+    gets the tool and so cannot terminate its own call (only the peer hanging up ends it)."""
+
+    enabled: bool = False
+    # Appended to the tool description to steer WHEN to end (LiveKit `extra_description`),
+    # e.g. "only after the caller confirms they need nothing else". Empty = generic default.
+    instructions: str = ""
+    # What the agent says right before hanging up (LiveKit `end_instructions`).
+    goodbye: str = "say goodbye to the user"
+    # Delete the room on end, disconnecting everyone incl. the SIP/phone leg (LiveKit
+    # `delete_room`). True is correct for a 1:1 phone/web call — it actually drops the line.
+    delete_room: bool = True
+
+
+class ComplianceConfig(BaseModel):
+    """HIPAA/BAA gate. Declaring `hipaa: true` marks the agent as handling PHI. Until
+    `baa_attested: true`, `kelam verify`/`deploy` refuse to ship it — you must have BAAs
+    signed with every provider in the call path first (Twilio, LiveKit, Deepgram,
+    ElevenLabs, Anthropic, AWS). When `hipaa: true`, call recording defaults OFF (the
+    worker skips egress) so PHI isn't captured to S3 without a BAA.
+
+    This is a guard against accidentally routing real PHI before BAAs exist, plus a safe
+    default — it does NOT by itself make the agent HIPAA-compliant."""
+
+    hipaa: bool = False
+    baa_attested: bool = False
+
+
+# Providers in a call's data path that would need a signed BAA before real PHI flows.
+# LiveKit is in the path even though we call LLM/STT/TTS directly: it carries the audio
+# (SIP/WebRTC transport), runs the turn detector over transcript text (inference.TurnDetector,
+# LiveKit Inference), and performs egress uploads from its own infra.
+_PHI_PROVIDERS = "Twilio, LiveKit, Deepgram, ElevenLabs, Anthropic, AWS"
+
+
+class AgentConfig(BaseModel):
+    """The agent.yaml contract — pure user intent. Server facts live in AgentRecord."""
+
+    name: str
+    description: str = ""
+    # The call's language (BCP-47, e.g. "es", "fr-CA"). One knob: it derives stt.language,
+    # is enforced on TTS where supported, and steers the prompt + turn detector. Greeting
+    # and scenarios should be written in this language. Fixed per agent — no mid-call
+    # switching (use stt.language: multi for code-switching callers).
+    language: str = "en"
+    # Enhanced noise cancellation on the caller's audio before STT, for callers in noisy
+    # places. "nc" removes environmental noise at no extra cost; "bvc_telephony" also
+    # suppresses competing background voices (extra cost); "off" passes raw audio. See
+    # registry.NOISE_CANCELLATION. Requires LiveKit Cloud transport (we run on it).
+    noise_cancellation: Literal["nc", "bvc_telephony", "off"] = "nc"
+    llm: LLMConfig = Field(default_factory=LLMConfig)
+    stt: STTConfig = Field(default_factory=STTConfig)
+    tts: TTSConfig = Field(default_factory=TTSConfig)
+    turn: TurnConfig = Field(default_factory=TurnConfig)
+    greeting: GreetingConfig = Field(default_factory=GreetingConfig)
+    phone: PhoneConfig = Field(default_factory=PhoneConfig)
+    end_call: EndCallConfig = Field(default_factory=EndCallConfig)
+    compliance: ComplianceConfig = Field(default_factory=ComplianceConfig)
+
+    def compliance_issues(self) -> list[str]:
+        """Blocking compliance problems (empty = ok). The HIPAA/BAA gate: an agent that
+        declares PHI handling must not ship until BAAs are attested. Surfaced by
+        `kelam verify` and enforced by `deploy` (which refuses to assemble the runtime)."""
+        if self.compliance.hipaa and not self.compliance.baa_attested:
+            return [
+                "compliance: hipaa=true but baa_attested=false — do not deploy until BAAs "
+                f"are signed with every provider in the call path ({_PHI_PROVIDERS}), then "
+                "set compliance.baa_attested: true"
+            ]
+        return []
+
+    @model_validator(mode="after")
+    def _languages_consistent(self) -> "AgentConfig":
+        """Derive stt.language from the agent language and reject combinations the
+        pipeline can't actually run — this is what makes `kelam verify` catch them
+        instead of the call failing live."""
+        stt_langs = registry.STT_LANGUAGES[self.stt.model]
+        # An English stt.language under a non-English agent language is treated as unset,
+        # not a conflict: every pulled agent.yaml carries the normalized English default,
+        # so "pull, set language: es, push" must derive rather than reject.
+        stale_english_default = (
+            registry.base_language(self.stt.language) == "en"
+            and registry.base_language(self.language) != "en"
+        )
+        if "language" not in self.stt.model_fields_set or stale_english_default:
+            if registry.base_language(self.language) != "en":
+                # exact tag if the STT model knows it, else its base language
+                for candidate in (self.language, registry.base_language(self.language)):
+                    if candidate in stt_langs:
+                        self.stt.language = candidate
+                        break
+                else:
+                    raise ValueError(
+                        f"language {self.language!r} is not supported by {self.stt.model}; "
+                        f"supported: {sorted(stt_langs)}"
+                    )
+        elif self.stt.language not in stt_langs:
+            raise ValueError(
+                f"stt.language {self.stt.language!r} is not supported by {self.stt.model}; "
+                f"supported: {sorted(stt_langs)}"
+            )
+        elif (self.stt.language != "multi"
+              and registry.base_language(self.stt.language) != registry.base_language(self.language)):
+            raise ValueError(
+                f"stt.language {self.stt.language!r} does not match the agent language "
+                f"{self.language!r} — set language alone (stt.language is derived from it), "
+                "or use stt.language: multi for code-switching"
+            )
+        tts_lang = registry.tts_language(self.language)
+        if tts_lang not in registry.TTS_LANGUAGES[self.tts.model]:
+            speakers = [m for m, langs in registry.TTS_LANGUAGES.items() if tts_lang in langs]
+            hint = f"models that can: {speakers}" if speakers else "no curated TTS model can"
+            raise ValueError(
+                f"{registry.language_name(self.language)} ({self.language!r}) is not spoken "
+                f"by {self.tts.model}; {hint}"
+            )
+        return self
+
+    def to_yaml(self) -> str:
+        return yaml.safe_dump(self.model_dump(), sort_keys=False)
+
+    @classmethod
+    def from_yaml(cls, text: str) -> "AgentConfig":
+        return cls(**(yaml.safe_load(text) or {}))
+
+
+class Scenario(BaseModel):
+    name: str
+    body: str = ""
+
+
+class TranscriptSegment(BaseModel):
+    role: Literal["user", "assistant", "agent", "system", "tool"]
+    text: str
+
+
+class TurnLatency(BaseModel):
+    """Per-turn pipeline latency captured by the worker from LiveKit metrics events,
+    keyed by the turn's speech_id. Parts are seconds; a part is None when that stage
+    didn't report for the turn (e.g. EOU metrics aren't emitted under stt-based turn
+    detection, and an interrupted turn may never reach TTS)."""
+
+    speech_id: str
+    eou_delay: float | None = None
+    llm_ttft: float | None = None
+    tts_ttfb: float | None = None
+
+
+class CallLog(BaseModel):
+    call_id: str
+    agent_id: str
+    workspace: str
+    # "web" is a browser test call (WebRTC, no phone number) placed from the test page.
+    direction: Literal["inbound", "outbound", "web"]
+    from_number: str | None = None
+    to_number: str | None = None
+    started_at: datetime
+    ended_at: datetime | None = None
+    duration_seconds: float | None = None
+    status: Literal["completed", "no_answer", "failed", "busy", "in_progress"] = "in_progress"
+    transcript: list[TranscriptSegment]
+    recording_url: str
+    # Short-lived presigned HTTPS link to the recording, minted on read from recording_url
+    # (issue #61). Derived, never persisted — absent on stored records and on calls with no
+    # recording yet (in_progress / failed dials).
+    recording_playback_url: str | None = None
+    # Optional so records written before the worker captured latency still validate.
+    turn_metrics: list[TurnLatency] | None = None
+
+
+class MessageLog(BaseModel):
+    """One message (SMS/MMS today; WhatsApp-ready), either direction. A thread is keyed
+    by (agent_id, peer_number); peer_number is the external party — to_number when we
+    send, from_number when they do. Statuses are the provider's lifecycle vocabulary
+    (Twilio's set)."""
+
+    message_id: str
+    agent_id: str
+    workspace: str
+    direction: Literal["inbound", "outbound"]
+    from_number: str
+    to_number: str
+    peer_number: str
+    body: str = ""
+    # MMS attachments (images etc.) by URL; a message needs a body or media, not both.
+    media_urls: list[str] = Field(default_factory=list)
+    # Delivery channel. SMS today; "whatsapp" is wired through the connector contract so
+    # WhatsApp slots in without a data migration (existing rows default to "sms"). A reply
+    # must go out on the same channel it arrived on.
+    channel: Literal["sms", "whatsapp"] = "sms"
+    status: Literal["queued", "accepted", "sending", "sent", "delivered",
+                    "undelivered", "failed", "received"] = "queued"
+    provider: str = "twilio"
+    provider_sid: str | None = None
+    created_at: datetime
+    error: str | None = None
+
+    @model_validator(mode="after")
+    def _has_content(self) -> "MessageLog":
+        if not self.body and not self.media_urls:
+            raise ValueError("message needs a body or at least one media URL")
+        return self
+
+
+class AgentRecord(BaseModel):
+    """Server-managed facts about an agent (written to .agentmeta.json on pull, never edited)."""
+
+    agent_id: str
+    workspace: str
+    version: str
+    phone_numbers: list[str] = Field(default_factory=list)
+    created_at: datetime
+    updated_at: datetime

kelam_core-0.1.0/kelam_core/translation.py

@@ -0,0 +1,60 @@
+"""The translation layer: agent folder  <->  JSON records.
+
+This is the pull/push contract. `folder_to_records` runs on push (CLI side),
+`records_to_folder` runs on pull. The records dict is what the DynamoDB repository
+stores (one item per piece). Tools are stored as raw code text; their metadata is
+derived by importing through kelam.tools (the one shared loader) — never re-parsed.
+
+Records shape:
+    {
+      "config":    {<AgentConfig fields>},
+      "scenarios": {"<name>": "<markdown body>", ...},
+      "tools":     {"<filename.py>": "<code text>", ...},
+    }
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from kelam_core.schemas import AgentConfig
+
+CONFIG_FILE = "agent.yaml"
+SCENARIOS_DIR = "scenarios"
+TOOLS_DIR = "tools"
+_INGEST = {CONFIG_FILE}  # plus scenarios/*.md and tools/*.py
+
+
+def folder_to_records(src: str | Path) -> dict:
+    """Parse a local agent folder into JSON records (push). Validates the config."""
+    src = Path(src)
+    config = AgentConfig.from_yaml((src / CONFIG_FILE).read_text(encoding="utf-8"))
+    scenarios = {
+        p.stem: p.read_text(encoding="utf-8")
+        for p in sorted((src / SCENARIOS_DIR).glob("*.md"))
+    }
+    tools = {
+        p.name: p.read_text(encoding="utf-8")
+        for p in sorted((src / TOOLS_DIR).glob("*.py"))
+    }
+    return {"config": config.model_dump(), "scenarios": scenarios, "tools": tools}
+
+
+def records_to_folder(records: dict, dest: str | Path) -> Path:
+    """Materialize JSON records into a local agent folder (pull)."""
+    dest = Path(dest)
+    dest.mkdir(parents=True, exist_ok=True)
+
+    config = AgentConfig(**records["config"])
+    (dest / CONFIG_FILE).write_text(config.to_yaml(), encoding="utf-8")
+
+    sdir = dest / SCENARIOS_DIR
+    sdir.mkdir(exist_ok=True)
+    for name, body in (records.get("scenarios") or {}).items():
+        (sdir / f"{name}.md").write_text(body, encoding="utf-8")
+
+    tdir = dest / TOOLS_DIR
+    tdir.mkdir(exist_ok=True)
+    for filename, code in (records.get("tools") or {}).items():
+        (tdir / filename).write_text(code, encoding="utf-8")
+
+    return dest

kelam_core-0.1.0/kelam_core.egg-info/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: kelam-core
+Version: 0.1.0
+Summary: Shared Kelam contracts: agent schemas, folder<->record translation, model registry, call metrics.
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pyyaml<7,>=6.0

kelam_core-0.1.0/kelam_core.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+pyproject.toml
+kelam_core/__init__.py
+kelam_core/metrics.py
+kelam_core/registry.py
+kelam_core/schemas.py
+kelam_core/translation.py
+kelam_core.egg-info/PKG-INFO
+kelam_core.egg-info/SOURCES.txt
+kelam_core.egg-info/dependency_links.txt
+kelam_core.egg-info/requires.txt
+kelam_core.egg-info/top_level.txt

kelam_core-0.1.0/kelam_core.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kelam_core-0.1.0/kelam_core.egg-info/requires.txt

@@ -0,0 +1,2 @@
+pydantic<3,>=2.7
+pyyaml<7,>=6.0

kelam_core-0.1.0/kelam_core.egg-info/top_level.txt

@@ -0,0 +1 @@
+kelam_core

kelam_core-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "kelam-core"
+version = "0.1.0"
+description = "Shared Kelam contracts: agent schemas, folder<->record translation, model registry, call metrics."
+requires-python = ">=3.11"
+# Capped at the next major per the repo dep policy (issue #40).
+dependencies = [
+  "pydantic>=2.7,<3",
+  "pyyaml>=6.0,<7",
+]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["kelam_core*"]

kelam_core-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+