contextir 1.0.1__py3-none-any.whl

contextir/__init__.py

@@ -0,0 +1,23 @@
+from contextir.clients import ModelResponse, OllamaClient, OpenAICompatibleClient
+from contextir.gateway import ContractCheck, ContextBundle, ContextIR, SIRKernel, load_contextir, load_kernel
+from contextir.pipeline import ContextPipeline, PipelinePolicy, PipelineResult, PreparedContext, ResponseVerification
+
+__version__ = "1.0.1"
+
+__all__ = [
+    "ContextIR",
+    "ContextPipeline",
+    "ModelResponse",
+    "OllamaClient",
+    "OpenAICompatibleClient",
+    "PipelinePolicy",
+    "PipelineResult",
+    "PreparedContext",
+    "ResponseVerification",
+    "ContractCheck",
+    "ContextBundle",
+    "SIRKernel",
+    "__version__",
+    "load_contextir",
+    "load_kernel",
+]

contextir/clients.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ModelResponse:
+    text: str
+    prompt_tokens: int | None = None
+    output_tokens: int | None = None
+    prompt_ms: float | None = None
+    generation_ms: float | None = None
+    latency_ms: float | None = None
+
+
+class OllamaClient:
+    """Dependency-free callable client for a local Ollama chat endpoint."""
+
+    def __init__(
+        self,
+        model: str,
+        base_url: str = "http://127.0.0.1:11434",
+        timeout: float = 180,
+        context_length: int = 32768,
+        max_output_tokens: int = 256,
+        temperature: float = 0,
+        seed: int = 42,
+    ) -> None:
+        if not model.strip():
+            raise ValueError("model must not be empty")
+        validate_endpoint(base_url, timeout, max_output_tokens)
+        if context_length < 1:
+            raise ValueError("context_length must be positive")
+        self.model = model
+        self.url = base_url.rstrip("/") + "/api/chat"
+        self.timeout = timeout
+        self.context_length = context_length
+        self.max_output_tokens = max_output_tokens
+        self.temperature = temperature
+        self.seed = seed
+
+    def __call__(self, prompt: str) -> str:
+        return self.complete(prompt).text
+
+    def complete(self, prompt: str) -> ModelResponse:
+        started = time.perf_counter()
+        result = post_json(
+            self.url,
+            {
+                "model": self.model,
+                "messages": [{"role": "user", "content": prompt}],
+                "stream": False,
+                "think": False,
+                "options": {
+                    "temperature": self.temperature,
+                    "seed": self.seed,
+                    "num_ctx": self.context_length,
+                    "num_predict": self.max_output_tokens,
+                },
+            },
+            timeout=self.timeout,
+        )
+        try:
+            text = str(result["message"]["content"]).strip()
+        except (KeyError, TypeError) as exc:
+            raise RuntimeError(f"invalid Ollama response from {self.url}: {exc}") from exc
+        return ModelResponse(
+            text=text,
+            prompt_tokens=as_int(result.get("prompt_eval_count")),
+            output_tokens=as_int(result.get("eval_count")),
+            prompt_ms=ns_to_ms(result.get("prompt_eval_duration")),
+            generation_ms=ns_to_ms(result.get("eval_duration")),
+            latency_ms=round((time.perf_counter() - started) * 1000, 3),
+        )
+
+
+class OpenAICompatibleClient:
+    """Dependency-free callable client for OpenAI-compatible chat endpoints."""
+
+    def __init__(
+        self,
+        model: str,
+        base_url: str = "http://127.0.0.1:1234/v1",
+        api_key: str = "",
+        timeout: float = 180,
+        max_output_tokens: int = 256,
+        temperature: float = 0,
+        seed: int | None = 42,
+    ) -> None:
+        if not model.strip():
+            raise ValueError("model must not be empty")
+        validate_endpoint(base_url, timeout, max_output_tokens)
+        self.model = model
+        self.url = base_url.rstrip("/") + "/chat/completions"
+        self.api_key = api_key
+        self.timeout = timeout
+        self.max_output_tokens = max_output_tokens
+        self.temperature = temperature
+        self.seed = seed
+
+    def __call__(self, prompt: str) -> str:
+        return self.complete(prompt).text
+
+    def complete(self, prompt: str) -> ModelResponse:
+        payload: dict[str, Any] = {
+            "model": self.model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": self.temperature,
+            "max_tokens": self.max_output_tokens,
+        }
+        if self.seed is not None:
+            payload["seed"] = self.seed
+        started = time.perf_counter()
+        result = post_json(
+            self.url,
+            payload,
+            timeout=self.timeout,
+            headers={"Authorization": f"Bearer {self.api_key}"} if self.api_key else None,
+        )
+        usage = result.get("usage", {})
+        try:
+            text = str(result["choices"][0]["message"]["content"]).strip()
+        except (IndexError, KeyError, TypeError) as exc:
+            raise RuntimeError(f"invalid OpenAI-compatible response from {self.url}: {exc}") from exc
+        return ModelResponse(
+            text=text,
+            prompt_tokens=as_int(usage.get("prompt_tokens")),
+            output_tokens=as_int(usage.get("completion_tokens")),
+            latency_ms=round((time.perf_counter() - started) * 1000, 3),
+        )
+
+
+def post_json(
+    url: str,
+    payload: dict[str, Any],
+    timeout: float,
+    headers: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    request_headers = {"Content-Type": "application/json", **(headers or {})}
+    request = urllib.request.Request(
+        url,
+        data=json.dumps(payload).encode("utf-8"),
+        headers=request_headers,
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"HTTP {exc.code} from {url}: {detail}") from exc
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"cannot reach model endpoint {url}: {exc.reason}") from exc
+    except (KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
+        raise RuntimeError(f"invalid model response from {url}: {exc}") from exc
+
+
+def as_int(value: Any) -> int | None:
+    return int(value) if value is not None else None
+
+
+def ns_to_ms(value: Any) -> float | None:
+    return round(float(value) / 1_000_000, 3) if value is not None else None
+
+
+def validate_endpoint(base_url: str, timeout: float, max_output_tokens: int) -> None:
+    if not base_url.startswith(("http://", "https://")):
+        raise ValueError("base_url must use http or https")
+    if timeout <= 0:
+        raise ValueError("timeout must be positive")
+    if max_output_tokens < 1:
+        raise ValueError("max_output_tokens must be positive")
+
+
+__all__ = ["ModelResponse", "OllamaClient", "OpenAICompatibleClient"]

contextir/dataset.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import json
+import random
+from pathlib import Path
+from typing import Iterable
+
+from contextir.tokenizer import normalize
+
+
+ENTITIES = [
+    ("cat", "кошка", "the cat", ["кошка", "животное", "питомец"], ["the cat", "an animal", "a pet"]),
+    ("dog", "собака", "the dog", ["собака", "пёс", "животное"], ["the dog", "a dog", "an animal"]),
+    ("child", "ребёнок", "the child", ["ребёнок", "мальчик", "девочка"], ["the child", "a kid", "the youngster"]),
+    ("robot", "робот", "the robot", ["робот", "машина", "автомат"], ["the robot", "a machine", "the automaton"]),
+    ("teacher", "учитель", "the teacher", ["учитель", "преподаватель", "наставник"], ["the teacher", "the instructor", "the mentor"]),
+    ("bird", "птица", "the bird", ["птица", "пернатое", "животное"], ["the bird", "a bird", "the animal"]),
+]
+
+ACTIONS = [
+    ("sitting", "сидит", "is sitting", ["сидит", "находится", "расположена"], ["is sitting", "is located", "is"]),
+    ("standing", "стоит", "is standing", ["стоит", "находится", "расположена"], ["is standing", "is located", "is"]),
+    ("sleeping", "спит", "is sleeping", ["спит", "дремлет", "отдыхает"], ["is sleeping", "is napping", "is resting"]),
+    ("looking", "смотрит", "is looking", ["смотрит", "наблюдает", "глядит"], ["is looking", "is watching", "is gazing"]),
+    ("walking", "идёт", "is walking", ["идёт", "шагает", "движется"], ["is walking", "is moving", "is going"]),
+]
+
+PLACES = [
+    ("table", "на столе", "on the table", ["на столе", "сверху стола", "у стола"], ["on the table", "at the table", "near the table"]),
+    ("window", "у окна", "by the window", ["у окна", "возле окна", "рядом с окном"], ["by the window", "near the window", "at the window"]),
+    ("garden", "в саду", "in the garden", ["в саду", "среди растений", "на участке"], ["in the garden", "among plants", "outside"]),
+    ("room", "в комнате", "in the room", ["в комнате", "в помещении", "дома"], ["in the room", "indoors", "inside"]),
+    ("street", "на улице", "on the street", ["на улице", "на дороге", "снаружи"], ["on the street", "on the road", "outside"]),
+]
+
+
+def _record(entity: tuple, action: tuple, place: tuple) -> dict:
+    eid, ru_entity, en_entity, ru_entity_alts, en_entity_alts = entity
+    aid, ru_action, en_action, ru_action_alts, en_action_alts = action
+    pid, ru_place, en_place, ru_place_alts, en_place_alts = place
+    meaning_id = f"m_{eid}_{aid}_{pid}"
+    ru = f"{ru_entity} {ru_action} {ru_place}"
+    en = f"{en_entity} {en_action} {en_place}"
+    ru_paraphrases = [
+        f"{ru_place_alts[1]} {ru_action_alts[1]} {ru_entity_alts[0]}",
+        f"{ru_entity_alts[1]} {ru_action_alts[2]} {ru_place_alts[2]}",
+        f"{ru_entity_alts[2]} {ru_action_alts[0]} {ru_place_alts[0]}",
+    ]
+    en_paraphrases = [
+        f"{en_entity_alts[1]} {en_action_alts[1]} {en_place_alts[1]}",
+        f"{en_entity_alts[2]} {en_action_alts[2]} {en_place_alts[2]}",
+        f"{en_entity_alts[0]} {en_action_alts[0]} {en_place_alts[0]}",
+    ]
+    atoms = [f"object:{eid}", f"state:{aid}", f"place:{pid}"]
+    return {
+        "meaning_id": meaning_id,
+        "ru": ru,
+        "en": en,
+        "ru_paraphrases": ru_paraphrases,
+        "en_paraphrases": en_paraphrases,
+        "semantic_atoms": atoms,
+        "definition_ru": f"смысл: {ru_entity} {ru_action} {ru_place}",
+        "definition_en": f"meaning: {en_entity} {en_action} {en_place}",
+    }
+
+
+def build_meanings() -> list[dict]:
+    return [_record(e, a, p) for e in ENTITIES for a in ACTIONS for p in PLACES]
+
+
+def variants(record: dict, lang: str) -> list[str]:
+    if lang == "ru":
+        return [record["ru"], *record["ru_paraphrases"], record["definition_ru"]]
+    if lang == "en":
+        return [record["en"], *record["en_paraphrases"], record["definition_en"]]
+    raise ValueError(f"unsupported language: {lang}")
+
+
+def paired_examples(records: Iterable[dict]) -> list[dict]:
+    rows: list[dict] = []
+    for rec in records:
+        for ru_text in variants(rec, "ru"):
+            rows.append({"meaning_id": rec["meaning_id"], "source_lang": "ru", "target_lang": "en", "source": ru_text, "target": rec["en"], "semantic_atoms": rec["semantic_atoms"]})
+        for en_text in variants(rec, "en"):
+            rows.append({"meaning_id": rec["meaning_id"], "source_lang": "en", "target_lang": "ru", "source": en_text, "target": rec["ru"], "semantic_atoms": rec["semantic_atoms"]})
+    return rows
+
+
+def write_jsonl(path: str | Path, rows: Iterable[dict]) -> None:
+    with Path(path).open("w", encoding="utf-8") as f:
+        for row in rows:
+            f.write(json.dumps(row, ensure_ascii=False) + "\n")
+
+
+def read_jsonl(path: str | Path) -> list[dict]:
+    with Path(path).open("r", encoding="utf-8") as f:
+        return [json.loads(line) for line in f if line.strip()]
+
+
+def split_examples(rows: list[dict], seed: int, train_size: int, valid_size: int, test_size: int) -> tuple[list[dict], list[dict], list[dict]]:
+    grouped: dict[str, list[dict]] = {}
+    for row in rows:
+        grouped.setdefault(row["meaning_id"], []).append(row)
+    rng = random.Random(seed)
+    train: list[dict] = []
+    valid: list[dict] = []
+    test: list[dict] = []
+    for group in grouped.values():
+        rng.shuffle(group)
+        train.extend(group[:6])
+        valid.extend(group[6:8])
+        test.extend(group[8:])
+    rng.shuffle(train)
+    rng.shuffle(valid)
+    rng.shuffle(test)
+    return train[:train_size], valid[:valid_size], test[:test_size]
+
+
+def phrase_index(rows: Iterable[dict]) -> dict[str, dict]:
+    return {normalize(row["source"]): row for row in rows}
+

contextir/evaluation/__init__.py

@@ -0,0 +1 @@
+

contextir/evaluation/metrics.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import difflib
+import time
+from pathlib import Path
+
+import numpy as np
+
+from contextir.models.baseline_translator import BaselineTranslator
+from contextir.models.semantic_encoder import SemanticEncoder
+from contextir.models.semantic_translator import SemanticTranslator, cosine
+from contextir.tokenizer import normalize, token_accuracy
+
+
+def char_similarity(pred: str, gold: str) -> float:
+    return difflib.SequenceMatcher(None, normalize(pred), normalize(gold)).ratio()
+
+
+def translation_metrics(predictions: list[tuple[str, str]]) -> dict[str, float]:
+    if not predictions:
+        return {"exact_match": 0.0, "token_accuracy": 0.0, "char_similarity": 0.0}
+    exact = [normalize(p) == normalize(g) for p, g in predictions]
+    return {
+        "exact_match": float(np.mean(exact)),
+        "token_accuracy": float(np.mean([token_accuracy(p, g) for p, g in predictions])),
+        "char_similarity": float(np.mean([char_similarity(p, g) for p, g in predictions])),
+    }
+
+
+def semantic_coherence(rows: list[dict], encoder: SemanticEncoder) -> dict[str, float]:
+    vectors = [(row["meaning_id"], encoder.encode_text(row["source"])) for row in rows]
+    intra: list[float] = []
+    inter: list[float] = []
+    for i in range(len(vectors)):
+        for j in range(i + 1, len(vectors)):
+            score = cosine(vectors[i][1], vectors[j][1])
+            if vectors[i][0] == vectors[j][0]:
+                intra.append(score)
+            else:
+                inter.append(score)
+    intra_mean = float(np.mean(intra)) if intra else 0.0
+    inter_mean = float(np.mean(inter)) if inter else 0.0
+    return {
+        "intra_cluster_similarity": intra_mean,
+        "inter_cluster_similarity": inter_mean,
+        "semantic_gap": intra_mean - inter_mean,
+    }
+
+
+def evaluate_baseline(rows: list[dict], baseline: BaselineTranslator) -> dict[str, float]:
+    return translation_metrics([(baseline.translate(row["source"]), row["target"]) for row in rows])
+
+
+def evaluate_semantic(rows: list[dict], encoder: SemanticEncoder, translator: SemanticTranslator) -> dict[str, float]:
+    preds = []
+    for row in rows:
+        pred, _, _, _ = translator.translate(row["source"], row["target_lang"], encoder)
+        preds.append((pred, row["target"]))
+    return translation_metrics(preds)
+
+
+def cycle_consistency(rows: list[dict], encoder: SemanticEncoder, translator: SemanticTranslator) -> float:
+    scores: list[float] = []
+    for row in rows:
+        original = encoder.encode_text(row["source"])
+        translated, _, _, _ = translator.translate(row["source"], row["target_lang"], encoder)
+        after = encoder.encode_text(translated)
+        scores.append(cosine(original, after))
+    return float(np.mean(scores)) if scores else 0.0
+
+
+def ablation_quality(rows: list[dict], encoder: SemanticEncoder, translator: SemanticTranslator, seed: int) -> dict[str, float]:
+    rng = np.random.default_rng(seed)
+    vectors = [encoder.encode_text(row["source"]) for row in rows]
+    rng.shuffle(vectors)
+    preds = []
+    for row, vector in zip(rows, vectors):
+        pred, _, _ = translator.translate_vector(vector, row["target_lang"])
+        preds.append((pred, row["target"]))
+    return translation_metrics(preds)
+
+
+def latency_ms(rows: list[dict], fn) -> float:
+    start = time.perf_counter()
+    for row in rows:
+        fn(row)
+    elapsed = time.perf_counter() - start
+    return float((elapsed / max(len(rows), 1)) * 1000)
+
+
+def file_size(path: str | Path) -> int:
+    p = Path(path)
+    return p.stat().st_size if p.exists() else 0
+