Metadata-Version: 2.4
Name: jit-protocol
Version: 1.2.0
Summary: Just-In-Time Protocol Synthesis Framework: Dynamic-to-Static API Generation using TypeSafe (Jev) and Needle
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: cactus-needle>=3.0.0
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == "fastapi"
Requires-Dist: uvicorn>=0.20.0; extra == "fastapi"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.20.0; extra == "test"

# JIT Protocol Synthesis Framework - Python Engine (`jit-api-python`)

> **基於 TypeSafe (Jev) 與 Cactus Needle 3.0 的原生 Python 動態至靜態 API 合成引擎**  
> *Pythonic Native Host Engine for Just-In-Time Protocol Synthesis*

---

## 🌟 特色

1. **同進程 Cactus Needle 3.0 端側推論**：
   在無 `TYPESAFE_API_KEY` 或離線狀態下，直接調用進程內的 Needle 3 SAN (2-bit, 35MB) 進行毫秒級 Tool Calling 與結構萃取，**0 網路轉發延遲、0 API 費用**。
2. **極致優雅的裝飾器語法**：
   使用 `@engine.route(...)` 宣告語意意圖，無縫支援 `async def` 與同步 `def` 函式。
3. **Pydantic v2 動態模型極速路徑**：
   當路由結構在過去 N 次請求中穩定後，自動生成動態 Pydantic v2 BaseModel，Phase 3 靜態驗證僅需 **0.03ms (0ms AI 延遲)**！
4. **自動版本演進與降級保護**：
   若遇到型態漂移（Schema Drift），自動降級回 Phase 1 並開啟 v2 / v3 版本的觀測與合約重新凍結。
5. **多語言程式碼生成積木**：
   凍結時同步輸出 TypeScript (Zod)、Golang (.proto / struct) 與 Python (Pydantic / FastAPI)。

---

## 🚀 快速上手 (Quick Start)

### 1. 安裝套件
```bash
pip install jit-protocol
```

### 2. 宣告端點與執行
```python
import asyncio
from jit_api import JITEngine

engine = JITEngine(stability_threshold=3)

@engine.route(
    name="create_invoice",
    description="Issue a customer billing invoice",
    intent="Bill or invoice a customer for items",
    enum_fields={"currency": {"USD": "US Dollar", "EUR": "Euro"}}
)
async def create_invoice(payload, ctx):
    return {
        "invoice_id": "INV-100",
        "customer": payload.get("customer"),
        "amount": payload.get("amount"),
        "phase": ctx.phase,
    }

async def main():
    # 支援自然語言或鬆散 JSON
    res = await engine.execute({
        "message": "Please bill Wayne Corp for 500 dollars urgently",
        "customer": "Wayne Corp",
        "amount": 500,
        "currency": "USD"
    })
    print(res.data)

if __name__ == "__main__":
    asyncio.run(main())
```

---

## 🧪 執行測試與演示

```bash
# 執行全套 pytest 測試
PYTHONPATH=python pytest python/tests/ -v

# 執行端到端生命週期演示
PYTHONPATH=python python3 python/examples/demo_lifecycle.py
```
