jit-protocol 1.0.0__tar.gz

jit_protocol-1.0.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: jit-protocol
+Version: 1.0.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)
+
+### 執行環境 (Conda `toby`)
+```bash
+conda activate toby
+```
+
+### 宣告端點與執行
+```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 /home/toby/miniconda3/envs/toby/bin/pytest python/tests/ -v
+
+# 執行端到端生命週期演示
+PYTHONPATH=python /home/toby/miniconda3/envs/toby/bin/python python/examples/demo_lifecycle.py
+```

jit_protocol-1.0.0/README.md

@@ -0,0 +1,75 @@
+# 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)
+
+### 執行環境 (Conda `toby`)
+```bash
+conda activate toby
+```
+
+### 宣告端點與執行
+```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 /home/toby/miniconda3/envs/toby/bin/pytest python/tests/ -v
+
+# 執行端到端生命週期演示
+PYTHONPATH=python /home/toby/miniconda3/envs/toby/bin/python python/examples/demo_lifecycle.py
+```

jit_protocol-1.0.0/jit_api/__init__.py

@@ -0,0 +1,39 @@
+"""
+JIT Protocol Synthesis Framework - Python Host Engine (jit-api-python)
+Dynamic Semantic Negotiation ➔ Static Code Freeze ➔ Fallback
+Powered by TypeSafe (Jev) and Cactus Needle 3.0
+"""
+
+from .engine import JITEngine
+from .types import (
+    IRField,
+    IRSchema,
+    JITExecutionResult,
+    JITRequestContext,
+    LifecyclePhase,
+    RouteDefinition,
+    StabilityMetrics,
+)
+from .typesafe_client import TypeSafeClient
+from .needle_engine import NeedleEngine
+from .router import TypeSafeRouter
+from .observer import SchemaObserver
+from .fallback_handler import FallbackHandler
+from .codegen import CodegenEngine
+
+__all__ = [
+    "JITEngine",
+    "TypeSafeClient",
+    "NeedleEngine",
+    "TypeSafeRouter",
+    "SchemaObserver",
+    "FallbackHandler",
+    "CodegenEngine",
+    "IRField",
+    "IRSchema",
+    "JITExecutionResult",
+    "JITRequestContext",
+    "LifecyclePhase",
+    "RouteDefinition",
+    "StabilityMetrics",
+]

jit_protocol-1.0.0/jit_api/codegen.py

@@ -0,0 +1,188 @@
+import json
+import os
+from typing import Any, Dict, Optional
+from .types import IRField, IRSchema
+
+
+class CodegenEngine:
+    """
+    Compiles IRSchema into multi-language contracts (TypeScript, Go, Python, IR JSON).
+    """
+
+    def __init__(self, output_dir: Optional[str] = None):
+        self.output_dir = output_dir or os.path.abspath("generated")
+
+    def _ensure_dirs(self) -> None:
+        for sub in ["typescript", "golang", "python", "schemas"]:
+            os.makedirs(os.path.join(self.output_dir, sub), exist_ok=True)
+
+    def generate_python(self, schema: IRSchema) -> str:
+        fields_code = []
+        for f in schema.fields.values():
+            py_t = "str"
+            if f.type == "number":
+                py_t = "float"
+            elif f.type == "boolean":
+                py_t = "bool"
+            elif f.type == "array":
+                item_t = "float" if f.item_type == "number" else ("bool" if f.item_type == "boolean" else "str")
+                py_t = f"list[{item_t}]"
+            elif f.type == "object":
+                py_t = "dict[str, Any]"
+
+            if not f.required:
+                py_t = f"Optional[{py_t}] = None"
+
+            fields_code.append(f"    {f.name}: {py_t}")
+
+        return f'''"""
+AUTO-GENERATED BY JIT PROTOCOL SYNTHESIS FRAMEWORK (Python)
+Route: {schema.route} (v{schema.version})
+Frozen At: {schema.frozen_at}
+"""
+
+from typing import Any, Optional
+from pydantic import BaseModel
+from fastapi import APIRouter
+
+router = APIRouter(prefix="/{schema.route}", tags=["{schema.route}"])
+
+
+class {schema.name}(BaseModel):
+{chr(10).join(fields_code)}
+
+
+@router.post("/", response_model=dict[str, Any])
+async def handle_{schema.route.replace("-", "_")}(payload: {schema.name}):
+    return {{
+        "status": "success",
+        "route": "{schema.route}",
+        "version": {schema.version},
+        "data": payload.model_dump(),
+    }}
+'''
+
+    def generate_typescript(self, schema: IRSchema) -> str:
+        fields_code = []
+        for f in schema.fields.values():
+            z_t = "z.string()"
+            if f.type == "number":
+                z_t = "z.number()"
+            elif f.type == "boolean":
+                z_t = "z.boolean()"
+            elif f.type == "array":
+                item_z = "z.number()" if f.item_type == "number" else ("z.boolean()" if f.item_type == "boolean" else "z.string()")
+                z_t = f"z.array({item_z})"
+            elif f.type == "object":
+                z_t = "z.record(z.unknown())"
+
+            if not f.required:
+                z_t += ".optional()"
+            fields_code.append(f"  {f.name}: {z_t},")
+
+        return f'''/**
+ * AUTO-GENERATED BY JIT PROTOCOL SYNTHESIS FRAMEWORK (Python Host)
+ * Route: {schema.route} (v{schema.version})
+ */
+
+import {{ z }} from 'zod';
+
+export const {schema.name}Schema = z.object({{
+{chr(10).join(fields_code)}
+}});
+
+export type {schema.name} = z.infer<typeof {schema.name}Schema>;
+'''
+
+    def generate_golang(self, schema: IRSchema) -> Dict[str, str]:
+        # 1. Proto3
+        proto_fields = []
+        for idx, f in enumerate(schema.fields.values(), 1):
+            pr_t = "string"
+            if f.type == "number":
+                pr_t = "double"
+            elif f.type == "boolean":
+                pr_t = "bool"
+            elif f.type == "array":
+                pr_t = f"repeated {'double' if f.item_type == 'number' else 'string'}"
+            proto_fields.append(f"  {pr_t} {f.name} = {idx};")
+
+        proto = f'''// AUTO-GENERATED BY JIT PROTOCOL SYNTHESIS FRAMEWORK
+syntax = "proto3";
+
+package jit.v{schema.version};
+
+option go_package = "jit/gen/v{schema.version};jitv{schema.version}";
+
+message {schema.name} {{
+{chr(10).join(proto_fields)}
+}}
+'''
+        # 2. Go Struct
+        go_fields = []
+        for f in schema.fields.values():
+            field_name = "".join(part.capitalize() for part in f.name.split("_"))
+            go_t = "string"
+            if f.type == "number":
+                go_t = "float64"
+            elif f.type == "boolean":
+                go_t = "bool"
+            elif f.type == "array":
+                go_t = "[]float64" if f.item_type == "number" else "[]string"
+            elif f.type == "object":
+                go_t = "map[string]interface{}"
+            go_fields.append(f'\t{field_name} {go_t} `json:"{f.name}"`')
+
+        go_struct = f'''// AUTO-GENERATED BY JIT PROTOCOL SYNTHESIS FRAMEWORK
+package models
+
+type {schema.name} struct {{
+{chr(10).join(go_fields)}
+}}
+'''
+        return {"proto": proto, "golang": go_struct}
+
+    def compile(self, schema: IRSchema) -> Dict[str, Any]:
+        self._ensure_dirs()
+        base = schema.route.replace("-", "_")
+
+        py_code = self.generate_python(schema)
+        py_path = os.path.join(self.output_dir, "python", f"{base}.py")
+        with open(py_path, "w", encoding="utf-8") as f:
+            f.write(py_code)
+
+        ts_code = self.generate_typescript(schema)
+        ts_path = os.path.join(self.output_dir, "typescript", f"{base}.ts")
+        with open(ts_path, "w", encoding="utf-8") as f:
+            f.write(ts_code)
+
+        go_res = self.generate_golang(schema)
+        proto_path = os.path.join(self.output_dir, "golang", f"{base}.proto")
+        with open(proto_path, "w", encoding="utf-8") as f:
+            f.write(go_res["proto"])
+
+        go_path = os.path.join(self.output_dir, "golang", f"{base}.go")
+        with open(go_path, "w", encoding="utf-8") as f:
+            f.write(go_res["golang"])
+
+        ir_dict = {
+            "name": schema.name,
+            "version": schema.version,
+            "route": schema.route,
+            "fields": {k: v.__dict__ for k, v in schema.fields.items()},
+            "frozen_at": schema.frozen_at,
+        }
+        ir_path = os.path.join(self.output_dir, "schemas", f"{base}.json")
+        with open(ir_path, "w", encoding="utf-8") as f:
+            json.dump(ir_dict, f, indent=2)
+
+        return {
+            "schema": schema,
+            "files": {
+                "python": py_path,
+                "typescript": ts_path,
+                "proto": proto_path,
+                "golang": go_path,
+                "ir_json": ir_path,
+            },
+        }

jit_protocol-1.0.0/jit_api/engine.py

@@ -0,0 +1,200 @@
+import inspect
+import time
+from typing import Any, Callable, Dict, List, Optional, Type, Union
+from pydantic import BaseModel, ValidationError, create_model
+
+from .codegen import CodegenEngine
+from .fallback_handler import FallbackHandler
+from .needle_engine import NeedleEngine
+from .observer import SchemaObserver
+from .router import TypeSafeRouter
+from .types import (
+    IRSchema,
+    JITExecutionResult,
+    JITRequestContext,
+    RouteDefinition,
+    RouteHandler,
+)
+from .typesafe_client import TypeSafeClient
+
+
+class JITEngine:
+    def __init__(
+        self,
+        client: Optional[TypeSafeClient] = None,
+        needle_engine: Optional[NeedleEngine] = None,
+        stability_threshold: int = 5,
+        confidence_threshold: float = 0.85,
+        fallback_to_needle: bool = True,
+        force_needle: bool = False,
+        codegen_output_dir: Optional[str] = None,
+        on_freeze: Optional[Callable[[Dict[str, Any]], None]] = None,
+        on_drift: Optional[Callable[[str, str], None]] = None,
+    ):
+        self.router = TypeSafeRouter(
+            client=client,
+            needle_engine=needle_engine,
+            fallback_to_needle=fallback_to_needle,
+            force_needle=force_needle,
+        )
+        self.codegen = CodegenEngine(codegen_output_dir)
+        self.fast_path_validators: Dict[str, Type[BaseModel]] = {}
+        self.on_freeze_callback = on_freeze
+        self.on_drift_callback = on_drift
+
+        async def _internal_on_freeze(schema: IRSchema):
+            # 1. Compile static files across TS, Go, Python, IR
+            codegen_res = self.codegen.compile(schema)
+
+            # 2. Build dynamic in-memory Pydantic v2 validator for Phase 3
+            self._mount_fast_path_validator(schema)
+
+            if self.on_freeze_callback:
+                if inspect.iscoroutinefunction(self.on_freeze_callback):
+                    await self.on_freeze_callback(codegen_res)
+                else:
+                    self.on_freeze_callback(codegen_res)
+
+        def _internal_on_drift(route: str, error: str, payload: Dict[str, Any]):
+            # Remove fast-path validator to re-enter dynamic Phase 1 mode
+            self.fast_path_validators.pop(route, None)
+            if self.on_drift_callback:
+                self.on_drift_callback(route, error)
+
+        self.observer = SchemaObserver(
+            stability_threshold=stability_threshold,
+            confidence_threshold=confidence_threshold,
+            on_freeze=_internal_on_freeze,
+        )
+
+        self.fallback = FallbackHandler(
+            router=self.router,
+            observer=self.observer,
+            on_drift_detected=_internal_on_drift,
+        )
+
+    def register(self, route_def: RouteDefinition) -> "JITEngine":
+        self.router.register(route_def)
+        return self
+
+    def route(
+        self,
+        name: str,
+        description: str,
+        intent: str,
+        enum_fields: Optional[Dict[str, Dict[str, str]]] = None,
+    ) -> Callable[[RouteHandler], RouteHandler]:
+        """
+        Pythonic decorator to register a route handler:
+        @engine.route(name="create_invoice", description="...", intent="...")
+        async def create_invoice(payload, ctx):
+            return {"status": "ok"}
+        """
+        return self.router.route(
+            name=name,
+            description=description,
+            intent=intent,
+            enum_fields=enum_fields,
+        )
+
+    def _mount_fast_path_validator(self, schema: IRSchema) -> None:
+        """
+        Dynamically create high-speed Pydantic v2 model for 0ms Phase 3 execution
+        """
+        field_definitions: Dict[str, Any] = {}
+
+        for name, field_meta in schema.fields.items():
+            py_type = str
+            if field_meta.type == "number":
+                py_type = float
+            elif field_meta.type == "boolean":
+                py_type = bool
+            elif field_meta.type == "array":
+                item_t = (
+                    float
+                    if field_meta.item_type == "number"
+                    else (bool if field_meta.item_type == "boolean" else str)
+                )
+                py_type = List[item_t]
+            elif field_meta.type == "object":
+                py_type = Dict[str, Any]
+
+            default_val = ... if field_meta.required else None
+            field_definitions[name] = (py_type, default_val)
+
+        model = create_model(f"{schema.name}FastValidator", **field_definitions)
+        self.fast_path_validators[schema.route] = model
+
+    async def execute(
+        self, payload: Dict[str, Any], explicit_route: Optional[str] = None
+    ) -> JITExecutionResult:
+        start_time = time.time()
+        target_route = explicit_route or (
+            payload.get("route") if isinstance(payload.get("route"), str) else None
+        )
+
+        is_target_frozen = target_route and self.observer.is_frozen(target_route)
+
+        # -------------------------------------------------------------
+        # Phase 3: Static Fast-Path (Pydantic v2, 0ms AI Latency)
+        # -------------------------------------------------------------
+        if is_target_frozen and target_route:
+            validator = self.fast_path_validators.get(target_route)
+            route_def = self.router.get_route(target_route)
+
+            if validator and route_def:
+                try:
+                    # Validate natively in-memory via Pydantic v2 C-extension
+                    validated = validator.model_validate(payload)
+                    clean_data = validated.model_dump()
+
+                    exec_time_ms = round((time.time() - start_time) * 1000, 2)
+                    ctx = JITRequestContext(
+                        route=target_route,
+                        phase="phase3_frozen",
+                        execution_time_ms=exec_time_ms,
+                        ai_latency_ms=0.0,  # 0ms AI latency!
+                        intent_confidence=1.0,
+                        is_fallback=False,
+                    )
+
+                    data = await self.router._invoke_handler(
+                        route_def.handler, clean_data, ctx
+                    )
+                    return JITExecutionResult(success=True, data=data, context=ctx)
+                except ValidationError as val_err:
+                    # Schema Drift detected! Downgrade to Phase 1 & re-arm Phase 2 for v2
+                    fallback_res = await self.fallback.handle_fallback(
+                        target_route, str(val_err), payload
+                    )
+                    return JITExecutionResult(
+                        success=True,
+                        data=fallback_res["result"],
+                        context=fallback_res["context"],
+                    )
+
+        # -------------------------------------------------------------
+        # Phase 1: Dynamic Semantic Routing (TypeSafe Jev or Needle)
+        # -------------------------------------------------------------
+        res = await self.router.handle(payload, preferred_route=target_route)
+
+        # Phase 2: Observation & Stability Tracking
+        obs = await self.observer.observe(
+            res["route"],
+            res["normalized_payload"],
+            res["context"].intent_confidence,
+        )
+
+        res["context"].phase = "phase3_frozen" if obs["stable"] else "phase1_dynamic"
+
+        return JITExecutionResult(
+            success=True, data=res["result"], context=res["context"]
+        )
+
+    def get_route_status(self, route: str) -> Dict[str, Any]:
+        return {
+            "route": route,
+            "is_frozen": self.observer.is_frozen(route),
+            "metrics": self.observer.get_metrics(route),
+            "frozen_schema": self.observer.get_frozen_schema(route),
+        }

jit_protocol-1.0.0/jit_api/fallback_handler.py

@@ -0,0 +1,51 @@
+import sys
+from typing import Any, Callable, Dict, Optional
+from .observer import SchemaObserver
+from .router import TypeSafeRouter
+
+
+class FallbackHandler:
+    """
+    Handles Phase 3 Fast-Path validation errors (Schema Drift)
+    by downgrading the request back to Phase 1 dynamic semantic resolution
+    and re-arming Phase 2 observation for the next contract version (v2, v3...).
+    """
+
+    def __init__(
+        self,
+        router: TypeSafeRouter,
+        observer: SchemaObserver,
+        on_drift_detected: Optional[Callable[[str, str, Dict[str, Any]], None]] = None,
+    ):
+        self.router = router
+        self.observer = observer
+        self.on_drift_detected = on_drift_detected or self._default_log_drift
+
+    @staticmethod
+    def _default_log_drift(route: str, error: str, payload: Dict[str, Any]) -> None:
+        sys.stderr.write(
+            f"[FallbackHandler] ⚠️ Schema drift detected on '{route}': {error}. Downgrading to Phase 1.\n"
+        )
+        sys.stderr.flush()
+
+    async def handle_fallback(
+        self, route: str, validation_error: str, raw_payload: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        # 1. Notify drift
+        self.on_drift_detected(route, validation_error, raw_payload)
+
+        # 2. Reset observer for this route to initiate v2 observation
+        self.observer.reset_route(route)
+
+        # 3. Reroute through Phase 1 dynamic semantic router
+        res = await self.router.handle(raw_payload, preferred_route=route)
+
+        # 4. Mark context as fallback
+        res["context"].is_fallback = True
+
+        # 5. Record drifted payload as sample 1 of the new version
+        await self.observer.observe(
+            route, res["normalized_payload"], res["context"].intent_confidence
+        )
+
+        return res