Metadata-Version: 2.4
Name: contlex
Version: 0.1.0
Summary: Reuse-first, domain-agnostic natural language parse module producing validated semantic frames.
Author: Sertan Özer
License: MIT
Project-URL: Homepage, https://github.com/sertanozer/contlex
Keywords: nlu,semantic-frame,structured-output,turkish
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.5
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Provides-Extra: llm
Requires-Dist: instructor>=1.0; extra == "llm"
Provides-Extra: local
Requires-Dist: outlines>=0.1; extra == "local"

# 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

```bash
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.

```bash
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:

```bash
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:

```bash
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

```python
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

```bash
pytest
```
