Metadata-Version: 2.4
Name: samlpy
Version: 0.2.0
Summary: SamlPy: Semantic Assembly Modeling Language for Python - Deterministic, Zero-Coordinate, LLM-Native CAD Engine built on OpenCASCADE
Author: CADi Team
License: MIT
Project-URL: Homepage, https://github.com/Omerersen/Project-CAD-
Project-URL: Repository, https://github.com/Omerersen/Project-CAD-
Keywords: cad,opencascade,brep,llm,ai,parametric,assembly,3d-modeling,saml,samlpy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Requires-Dist: numpy>=1.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"

# LLM-Dostu CAD Kütüphanesi ve Montaj Mimarisi Özellikleri (LLM CAD Library Specs)

Bu doküman, CADi (`Project-CAD-`) projemiz bünyesinde geliştirilecek LLM-dostu özel CAD kütüphanesi, montaj motoru, veri toplama boru hattı ve AI gateway altyapısının temel mimari gereksinimlerini ve tasarım ilkelerini içerir.

---

## 1. Neden Özel Bir LLM CAD Kütüphanesi / DSL?

Genel 3D CAD kütüphaneleri (CadQuery, OpenCASCADE, PythonOCC) insan geliştiriciler için tasarlanmıştır ve LLM'ler (Claude, GPT, DeepSeek) tarafından kodlandığında şu sorunlara yol açar:
* **Yüksek Token Maliyeti**: Basit bir parça veya montaj için yüzlerce satır detay kod üretilmesi.
* **Sentaks Hataları & Bağlam Kaybı**: Metod zincirleme (fluent API) yapılarının karmaşıklığı nedeniyle LLM'lerin sentaks hatası yapması.
* **Topolojik Kararsızlık**: Yüzey, delik ve kenarların adreslenmesinde illüzyon (hallucination) oluşması.

### 💡 Çözüm: LLM-Dostu Bildirimsel (Declarative) Kütüphane / DSL
LLM-dostu kütüphanemiz, Python tabanlı yalın bir sözdizimine (SAML - Spatial Assembly Modeling Language) sahip olacak ve doğrudan **OpenCASCADE (OCCT / OCP)** motoru üzerine kurulacaktır:

```
[SAML DSL (LLM Arayüzü)] 
         ↓
[SAML Compiler & IR (Kural ve İlişki Çözücü)] 
         ↓
[CADi OCCT Backend (Saf OpenCASCADE Çekirdeği)]
    ├── BRep & Topoloji Katmanı (TopoDS_Shape, Faces, Edges)
    ├── Doğrudan Montaj & Eklemler (Joints/Mates Motoru)
    └── Tersine Mühendislik & Import Motoru (STEP/IGES)
```

**Neden Doğrudan OpenCASCADE (OCCT)?**
* **Doğrudan B-Rep ve Topoloji Kontrolü**: CadQuery veya üçüncü parti wrapper'ların getirdiği adlandırma (naming) ve kararsızlık hataları kökten çözülür.
* **Tersine Mühendislik (STEP → SAML)**: STEP dosyalarının en saf haliyle okunup yüzey/delik analizi yapılması doğrudan OpenCASCADE API'leri ile kayıpsız çalışır.
* **Dış Katman Bağımsızlığı**: Gereksiz bağımlılıklar elenir, doğrudan endüstriyel C++ çekirdeği Python üzerinden kontrol edilir.

> **Strateji**: `reference_build123d` kaynak kodları incelenmiş olup; montaj eklemleri, B-Rep selektörleri ve STEP import gibi kritik alt yapılar kopyalanıp kendi OpenCASCADE altyapımıza uyarlanacaktır.

---

## 2. Kütüphanede Olması Gereken Temel Özellikler

### A. Üst Düzey Montaj ve İlişkilendirme (High-Level Assembly & Mates)
* Parçaları uzayda $X, Y, Z$ koordinatlarıyla elle yerleştirmek yerine CAD standartlarındaki **Montaj İlişkileri (Mates & Constraints)** kullanılır.
* **Örnek**:
  ```python
  Assembly.connect(partA.face("bottom"), partB.face("top"), mate_type="FLUSH", offset=0)
  Assembly.align_holes(partA.hole("h1"), partB.hole("h1"))
  ```
* **Kazanım**: LLM'in uzamsal matris hesaplama yükünü sıfırlar, token tüketimini %90 düşürür.

### B. Dahili Standart Parça Kütüphanesi (Built-in Standard Component Library)
* Cıvata, somun, rulman, alüminyum profil, motor gibi standart endüstriyel bileşenler LLM tarafından sıfırdan çizilmez, tek satırda çağrılır:
  ```python
  bolt1 = Fastener.ISO4762(size="M6", length=20)
  bearing1 = Bearing.SKF("608ZZ")
  motor1 = Component.NEMA17(length=40)
  ```
* **Kazanım**: 1000 token harcanacak standart bileşenler 5-10 token'a düşer.

### C. Çapa / Bağlantı Noktaları (Anchor Ports & Interfaces)
* Parçalar kendi üzerinde montaj portları barındırır:
  ```python
  Assembly.attach(motor.port("shaft"), wheel.port("hub"))
  ```
* **Kazanım**: Parçaların iç içe geçme ve çakışma (clash) hataları engellenir.

### D. Değişken Bağlamalı Parametrik Mimari (Cascading Parametric Variables)
* Tüm montaj tek bir ana değişkene (`Master Parameter`) bağlanır:
  ```python
  with Assembly("Gearbox") as app:
      app.set_param("box_width", 120)
      # Tüm iç parçalar box_width parametresine göre otomatik ölçeklenir
  ```
* **Kazanım**: Kullanıcı revizyon istediğinde LLM tüm kodu baştan yazmak yerine sadece 1 parametreyi değiştirir (%98 token tasarrufu).

### E. Dosyadan Koda Dönüşüm / Tersine Mühendislik (Import & Reverse Engineering)
* Mevcut endüstriyel CAD dosyaları (STEP, IGES, STL, DXF) doğrudan sisteme aktarılıp SAML koduna dönüştürülür:
  ```python
  # Dosyadan SAML kodu üret
  model = Assembly.from_step("gearbox.step")
  dsl_code = model.to_saml()           # → LLM-dostu SAML kodu
  params   = model.extract_params()    # → Parametrik değişkenler

  # Görsel teknik çizimden (OCR + AI)
  model = Assembly.from_drawing("blueprint.pdf", ocr=True)
  ```
* **Kazanım**:
  * Mevcut endüstriyel miras (legacy) dosyalar sisteme dahil edilebilir
  * `(STEP dosyası → SAML kodu)` çifti → Fine-tuning veri seti
  * Kullanıcı "bu parçayı al ve şu değişikliği yap" diyebilir (edit workflow)
  * DeepCAD transpiling adımını (Bölüm 3.2) otomatikleştirir

### F. Geometri Doğrulama Katmanı (Validation Engine)
* Üretilen veya içe aktarılan tüm geometri çalıştırılmadan önce doğrulanır:
  ```python
  validator = ValidationEngineer()
  validator.check_manifold(part)          # Su geçirmez kapalı yüzey mi?
  validator.check_tolerances(part)        # Üretim toleransları mantıklı mı?
  validator.check_assembly_clash(asm)     # Parçalar çakışıyor mu?
  validator.check_units_consistency(asm)  # mm/inch karışıklığı var mı?
  ```
* **Kazanım**: Hatalı geometri LLM'e yapılandırılmış doğal dil geri bildirimi olarak döner (stack trace yerine NL açıklama → LLM'in hatayı anlayıp düzeltmesi kolaylaşır).

### G. Versiyon Kontrolü ve Kısmi Revizyon (Versioning & Diff-Edit)
* Her SAML kodu commit'i parametreler + hash ile izlenir; LLM tüm kodu baştan yazmak yerine sadece değişen bloğu günceller:
  ```python
  # Parçayı tamamen yeniden yazmak yerine güncelle
  Assembly.update_part("gearbox", "cover", wall_thickness=3.5)
  Assembly.diff(v1, v2)   # → Değişen parametreler ve geometri farkı
  ```
* **Kazanım**: %95+ token tasarrufu, revizyon geçmişi izlenebilir, DPO/RLHF için negatif örnek kaydı.

### H. Zorunlu Metadata Şeması (Required Metadata)
* Her SAML dosyası üretim için gereken meta bilgileri içerir:
  ```python
  Assembly(
      name="GearboxV2",
      units="mm",                        # Zorunlu: mm | inch | m
      tolerance_standard="ISO 2768-m",   # Zorunlu: üretim toleransı
      material="AlSi10Mg",               # Opsiyonel: malzeme
      export=["STEP", "STL", "DXF"],    # Çıktı formatları
  )
  ```
* **Kazanım**: mm/inch karışıklığı ve tolerans hatası CAD'de ölümcüldür; DSL'de first-class citizen yapılması zorunludur.

### I. build123d'den Alınacak ve OpenCASCADE ile Özelleştirilecek Modüller

Proje dizinine indirilen (`library/reference_build123d`) kaynak kodlarından kütüphanemize doğrudan adapte edilecek kritik bileşenler:

1. **Montaj ve Eklem Sistemi (`joints.py`):**
   * *Neden gerekli?* `RigidJoint`, `RevoluteJoint`, `LinearJoint` gibi nesnelerin OpenCASCADE matris dönüşümlerine (`gp_Trsf`) nasıl bağlandığı hazır.
   * *Bizim uyarlamamız:* SAML'in `Assembly.connect(mate_type=...)` yapısına doğrudan entegre edilecek.

2. **Topoloji ve Yüzey Seçiciler (`topology/` & `geometry.py`):**
   * *Neden gerekli?* `Face.filter_by()`, `Edge.filter_by()`, en üst yüzeyi bulma (`>Z`), silindirik delikleri ayıklama mantığı.
   * *Bizim uyarlamamız:* Hallucination'ı önlemek için yüzeylere deterministik ID/çapa atayan modül olarak sadeleştirilecek.

3. **İçe Aktarma ve B-Rep Dönüşümü (`importers.py` & `brep_from_stl.py`):**
   * *Neden gerekli?* STEP ve STL dosyalarını OpenCASCADE nesnelerine (`TopoDS_Shape`, `TopoDS_Compound`) dönüştürme fonksiyonları.
   * *Bizim uyarlamamız:* `Assembly.from_step()` ve Tersine Mühendislik (Dosyadan SAML Koda) boru hattının çekirdeği yapılacak.

4. **Dışa Aktarma Motoru (`exporters.py` & `exporters3d.py`):**
   * *Neden gerekli?* Renk, malzeme, montaj hiyerarşisini kaybetmeden STEP/GLTF/STL formatlarına kaydetme algoritmaları.

---

## 3. Veri Toplama ve Fine-Tuning Hazırlık Stratejisi

Modeli kendi kütüphanemiz üzerinde eğitmek (Fine-Tune) için gereken `[İstek Metni ──> Bizim DSL Kodu ──> STEP/STL]` verisi 3 kanaldan toplanır:

### 1. Sentetik Veri Üretimi (Synthetic Data Pipeline)
1. **Parametrik Şablon Betikleri**: Python ile 50-100 temel parça ve montaj kategorisi (flanşlar, L-braketler, redüktörler, kasalar) yazılır. Parametreler rastgele değiştirilerek 50.000+ hatasız DSL kodu türetilir.
2. **Tersine Prompting (Reverse Prompting)**: Bu kodlar büyük bir LLM'e (Claude 3.5 / GPT-4o) verilerek Türkçe ve İngilizce kullanıcı istekleri (*"100x50mm flanş tasarla"*) ürettirilir.

### 2. Açık Kaynak Veri Dönüştürme (Transpiling)
* **DeepCAD (178.000 Onshape Modeli)** veritabanındaki JSON komut dizileri otomatik script ile kendi DSL formatımıza dönüştürülür.
* GitHub'daki CadQuery ve build123d repoları taranır.

### 3. Canlı Sistem Logları (Production Telemetry)
* **Başarılı Çıktılar (`gold_standard.jsonl`)**: OpenCASCADE doğrulamasından (`ValidationEngineer`) geçen hatasız kodlar otomatik veri setine kaydedilir.
* **Hatalı Çıktılar**: Hatalı üretilip düzeltilen kodlar modelin olumsuz örnekleri öğrenmesi için **DPO/RLHF** veri setine eklenir.

---

## 4. Altyapı & AI Gateway (OmniRoute Entegrasyonu)

* **Kesintisiz Çalışma (Auto-Fallback)**: Kotalar veya hız limitleri dolduğunda otomatik alternatif AI sağlayıcısına yönlendirme.
* **Token Sıkıştırması (RTK + Caveman)**: Bağlam ve prompt boyutu %15-%95 azaltılarak API maliyetleri düşürülür.
* **Çoklu Model Desteği**: Basit görevler için ücretsiz/ucuz modeller (Gemini Flash, lokal Ollama), karmaşık montajlar için üst düzey modeller (Claude 3.5 Sonnet) çağrılır.

---

## 5. Yol Haritası (Milestones)

1. [x] **Adım 1**: SAML / LLM-DSL sözdizimi ve SAML Compiler IR'ının (`ir/nodes.py`, `ir/parser.py`) netleştirilmesi.
2. [x] **Adım 2**: Backend Adapter katmanı (`backend/occt_backend.py` — saf OpenCASCADE/OCP çekirdeği ile bağımsız motor).
3. [x] **Adım 3**: Standart parça kütüphanesi (`Fastener.ISO4762`, `Bearing.SKF`, `Nut.DIN934`, `Washer.DIN125`, `Profile.VSlot`, `Motor.NEMA`).
4. [x] **Adım 4**: Geometri Doğrulama Motoru (`ValidationEngineer`) — Manifoldluk ve Çakışma (Clash) denetimi.
5. [x] **Adım 5**: Tersine Mühendislik pipeline'ı — `STEPReverseEngineer` ile STEP dosyasından otomatik SAML kod üretimi.
6. [ ] **Adım 6**: Sentetik veri üreteci (`scripts/synthetic_generator.py`) — 20k+ `(istek, SAML, STEP)` üçlüsü.
7. [ ] **Adım 7**: Qwen2.5-Coder veya DeepSeek modelinin LoRA/QLoRA ile eğitilmesi.
8. [ ] **Adım 8 (Uzun Vade)**: CADi Native Kernel — kendi geometri çekirdeği ile `build123d` bağımlılığının kaldırılması.

