contlex 0.1.0

Reuse-first, domain-agnostic natural language parse module producing validated semantic frames.

contlex

v1 | 2026-05-14 | contlex reuse-first domain-agnostic natural language parse module

contlex is a small, reuse-first, domain-agnostic Python package that turns natural language into a validated semantic frame. It does not decide, route, execute, mutate, or expose tools.

natural language
  → structured semantic frame
  → schema validation
  → consistency checks
  → evaluation
  → future adapters (Cont shadow, RAG_main query mock, …)

Positioning

• Cont ve RAG_main'den beslenen, ama ikisinden bağımsız çalışan parse paketi.
• Runtime bağımlılığı yok: Cont yürütmesi ya da KOSGEB karar grafı değişmez.
• domain alanı yoktur. Domain-specific parser yoktur.

v1 Başarı Kriteri

Her şeyi anlamak değil — anlamadığını işaretlemek ve anlam eklememek.

Kurulum

pip install -e .
# isteğe bağlı parser back-end (v1 default'unda yok):
pip install -e ".[llm]"   # instructor tabanlı LLM yolu
pip install -e ".[local]" # outlines tabanlı local model yolu
pip install -e ".[dev]"   # pytest

Prompt ile Hızlı Test

Varsayılan komut dependency-free heuristic baseline parser kullanır. Bu üretim parser'ı değildir; offline smoke test ve regression kontrolü içindir.

python3 -m contlex "Şu raporu silme" --issues

Beklenen sonuç: JSON semantic frame basılır; modality değeri prohibition, polarity değeri negative olur ve temiz örnekte issues: [] görünür.

Kurulum sonrası aynı komut script olarak da çalışır:

contlex "Şunu kaydet" --issues

Bu örnekte eksik referans nedeniyle needs_clarification: true ve missing_referent ambiguity beklenir.

Gerçek parser yolu, contlex'in structured contract'ını bir backend'e verip dönen JSON'u doğrulamaktır:

contlex "bütün sistemdeki jpg dosyalarını listele" --print-contract
contlex "bütün sistemdeki jpg dosyalarını listele" \
  --backend-command "your-parser-command" \
  --issues

your-parser-command stdin'den contract prompt'u almalı, stdout'a yalnızca semantic-frame JSON yazmalıdır. contlex sonra parse_frame ve consistency checks çalıştırır.

JSON ile Hızlı Kullanım

from contlex import parse_frame, parse_prompt, run_consistency_checks

frame = parse_prompt("Şu raporu silme")
print(frame.model_dump())

frame = parse_frame({
    "raw_text": "şu raporu silme",
    "canonical_text": "şu raporu silme",
    "language": "tr",
    "modality": "prohibition",
    "polarity": "negative",
    "slots": [
        {"key": "action", "value": "silme",
         "source_text": "silme", "confidence": "high"},
        {"key": "object", "value": "şu rapor",
         "source_text": "şu raporu", "confidence": "medium"},
    ],
    "missing_slots": [],
    "ambiguities": [
        {"type": "missing_referent",
         "where": "şu rapor",
         "reason": "referent belirsiz"}
    ],
    "needs_clarification": True,
    "confidence": "medium",
})

issues = run_consistency_checks(frame)
assert issues == []

Paket Yapısı

contlex/
  schema.py          # Pydantic semantic frame model
  contract.py        # external parser backend prompt/schema contract
  parser.py          # dependency-free heuristic baseline
  validator.py       # parse_frame, structural validation
  consistency.py     # 7 deterministic cross-field checks
  eval.py            # fixture-based metric harness
  adapters/
    cont_shadow_mock.py  # Cont mock adapter
    rag_query_mock.py    # RAG_main mock adapter

Reuse-First Karar

Yeni bir NLU framework icat etmiyoruz. contlex v1 ilk olarak:

• Pydantic v2 — frame modeli ve extra="forbid" ile strict validation
• instructor (opsiyonel) — LLM structured output + Pydantic retry
• outlines (opsiyonel) — local model için constrained generation

Rasa, spaCy Turkish, Stanza, Zemberek v1 fallback / helper aday listesindedir ama runtime bağımlılığı olarak getirilmez. Detay için docs/specs/contlex_reuse_research.md.

Non-Goals (v1)

• Domain-specific parser yok.
• Schema'da domain alanı yok.
• Cont runtime değişikliği yok.
• RAG_main / KOSGEB karar graph bağlantısı yok.
• Tool routing yok.
• Execution / write / delete / browser / shell davranışı yok.
• Custom model training yok.
• Yeni agent mimarisi yok.

Test

pytest