logic-fingerprint 0.1.0__tar.gz

logic_fingerprint-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: logic-fingerprint
+Version: 0.1.0
+Summary: Execution safety layer for functions, APIs, and LLMs.
+Author: Your Name
+License: MIT
+Keywords: llm,circuit-breaker,middleware,reliability,api,decorator
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=1.10
+
+
+Add a safety layer to any function.
+
+Logic Fingerprint protects your function/LLM/API calls with:
+
+circuit breaker (no retry storms)
+safe recovery (HALF_OPEN probing)
+schema validation (stable outputs)
+unified error handling
+
+Works with a single decorator: @protect()
+
+## 🧭 How it works
+
+```text
+Your Function
+      ↓
+   @protect
+      ↓
+Logic Fingerprint
+  ├─ Circuit Breaker
+  ├─ Probe Recovery
+  ├─ Validation Layer
+  ├─ Error Control
+      ↓
+ Safe Execution
+      ↓
+   Result / Error
+```
+
+## ⚡ Quick Start
+
+### Install
+
+```bash
+pip install -r requirements.txt
+pip install -e .
+```
+
+### Protect a real local LLM call
+
+```python
+from logic_fingerprint import protect
+
+
+@protect()
+def ask_local_llm(request):
+    import json
+    import urllib.request
+
+    payload = {
+        "model": "llama3.2",
+        "prompt": request.payload["prompt"],
+        "stream": False,
+    }
+
+    req = urllib.request.Request(
+        "http://127.0.0.1:11434/api/generate",
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+
+    with urllib.request.urlopen(req, timeout=60) as resp:
+        body = json.loads(resp.read().decode("utf-8"))
+
+    return {"answer": body["response"].strip()}
+```
+
+### Call it like a normal function
+
+```python
+result = ask_local_llm({
+    "prompt": "Explain circuit breaker in one sentence."
+})
+
+print(result)
+```
+
+Output:
+
+```python
+{'answer': 'A circuit breaker is a safety device that automatically stops an overcurrent flow in an electrical circuit to prevent damage to equipment and potential hazards.'}
+```
+
+### What you get automatically
+
+* circuit breaker protection
+* safe recovery probing
+* controlled failure handling
+* optional schema validation
+* auto request context
+
+
+
+```md
+## 🎬 Demos
+
+Run real examples locally:
+
+### 1. Simple mode (like a normal function)
+
+```bash
+python demo/demo_protect_simple.py
+```
+
+---
+
+### 2. Full mode (engineering output)
+
+```bash
+python demo/demo_protect_full.py
+```
+
+---
+
+### 3. Error handling (simple mode)
+
+```bash
+python demo/demo_error_simple.py
+```
+
+---
+
+### 4. Error handling (full mode)
+
+```bash
+python demo/demo_error_full.py
+```
+
+---
+
+### 5. Real LLM demo (Ollama)
+
+```bash
+python demo/demo_protect_ollama_simple.py
+```
+
+👉 Make sure Ollama is running locally before running this demo.
+
+------------------------------------------------------------------------
+
+**Logic Fingerprint — Execution Safety Layer (Python)**
+
+* Designed and implemented a decorator-based execution control layer for functions, APIs, and LLM calls
+* Built circuit breaker with HALF_OPEN recovery, time-driven probing, and consecutive-success gating
+* Added schema validation (Pydantic) and unified error protocol for stable, observable outputs
+* Delivered dual-mode API (`simple` vs `full`) to support both developer-friendly usage and production observability
+* Integrated with local LLM (Ollama) to demonstrate real-world stability against timeouts and malformed outputs
+* Structured demos and documentation to enable 30-second onboarding and clear behavior comparison
+
+
+Logic Fingerprint — 执行安全层（Python）
+
+设计并实现基于装饰器的执行控制层，用于函数 / API / LLM 调用的稳定性保护
+实现熔断机制（CLOSED / OPEN / HALF_OPEN）及时间驱动探测恢复与连续成功判定
+引入输入输出 Schema 校验（Pydantic）与统一错误协议，保证结果结构稳定、可观测
+设计双模式接口（simple / full），兼顾易用性与工程可观测性
+集成本地 LLM（Ollama）进行真实场景验证，解决 timeout、异常输出等问题
+构建分层 demo 与文档体系，实现 30 秒上手与行为对照演示
+
+---
+“I built a decorator-based execution safety layer for LLM and API calls.”
+

logic_fingerprint-0.1.0/README.md

@@ -0,0 +1,164 @@
+
+Add a safety layer to any function.
+
+Logic Fingerprint protects your function/LLM/API calls with:
+
+circuit breaker (no retry storms)
+safe recovery (HALF_OPEN probing)
+schema validation (stable outputs)
+unified error handling
+
+Works with a single decorator: @protect()
+
+## 🧭 How it works
+
+```text
+Your Function
+      ↓
+   @protect
+      ↓
+Logic Fingerprint
+  ├─ Circuit Breaker
+  ├─ Probe Recovery
+  ├─ Validation Layer
+  ├─ Error Control
+      ↓
+ Safe Execution
+      ↓
+   Result / Error
+```
+
+## ⚡ Quick Start
+
+### Install
+
+```bash
+pip install -r requirements.txt
+pip install -e .
+```
+
+### Protect a real local LLM call
+
+```python
+from logic_fingerprint import protect
+
+
+@protect()
+def ask_local_llm(request):
+    import json
+    import urllib.request
+
+    payload = {
+        "model": "llama3.2",
+        "prompt": request.payload["prompt"],
+        "stream": False,
+    }
+
+    req = urllib.request.Request(
+        "http://127.0.0.1:11434/api/generate",
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+
+    with urllib.request.urlopen(req, timeout=60) as resp:
+        body = json.loads(resp.read().decode("utf-8"))
+
+    return {"answer": body["response"].strip()}
+```
+
+### Call it like a normal function
+
+```python
+result = ask_local_llm({
+    "prompt": "Explain circuit breaker in one sentence."
+})
+
+print(result)
+```
+
+Output:
+
+```python
+{'answer': 'A circuit breaker is a safety device that automatically stops an overcurrent flow in an electrical circuit to prevent damage to equipment and potential hazards.'}
+```
+
+### What you get automatically
+
+* circuit breaker protection
+* safe recovery probing
+* controlled failure handling
+* optional schema validation
+* auto request context
+
+
+
+```md
+## 🎬 Demos
+
+Run real examples locally:
+
+### 1. Simple mode (like a normal function)
+
+```bash
+python demo/demo_protect_simple.py
+```
+
+---
+
+### 2. Full mode (engineering output)
+
+```bash
+python demo/demo_protect_full.py
+```
+
+---
+
+### 3. Error handling (simple mode)
+
+```bash
+python demo/demo_error_simple.py
+```
+
+---
+
+### 4. Error handling (full mode)
+
+```bash
+python demo/demo_error_full.py
+```
+
+---
+
+### 5. Real LLM demo (Ollama)
+
+```bash
+python demo/demo_protect_ollama_simple.py
+```
+
+👉 Make sure Ollama is running locally before running this demo.
+
+------------------------------------------------------------------------
+
+**Logic Fingerprint — Execution Safety Layer (Python)**
+
+* Designed and implemented a decorator-based execution control layer for functions, APIs, and LLM calls
+* Built circuit breaker with HALF_OPEN recovery, time-driven probing, and consecutive-success gating
+* Added schema validation (Pydantic) and unified error protocol for stable, observable outputs
+* Delivered dual-mode API (`simple` vs `full`) to support both developer-friendly usage and production observability
+* Integrated with local LLM (Ollama) to demonstrate real-world stability against timeouts and malformed outputs
+* Structured demos and documentation to enable 30-second onboarding and clear behavior comparison
+
+
+Logic Fingerprint — 执行安全层（Python）
+
+设计并实现基于装饰器的执行控制层，用于函数 / API / LLM 调用的稳定性保护
+实现熔断机制（CLOSED / OPEN / HALF_OPEN）及时间驱动探测恢复与连续成功判定
+引入输入输出 Schema 校验（Pydantic）与统一错误协议，保证结果结构稳定、可观测
+设计双模式接口（simple / full），兼顾易用性与工程可观测性
+集成本地 LLM（Ollama）进行真实场景验证，解决 timeout、异常输出等问题
+构建分层 demo 与文档体系，实现 30 秒上手与行为对照演示
+
+---
+“I built a decorator-based execution safety layer for LLM and API calls.”
+

logic_fingerprint-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "logic-fingerprint"
+version = "0.1.0"
+description = "Execution safety layer for functions, APIs, and LLMs."
+readme = "README.md"
+requires-python = ">=3.9"
+
+authors = [
+  { name = "Your Name" }
+]
+
+license = { text = "MIT" }
+
+dependencies = [
+  "pydantic>=1.10"
+]
+
+keywords = [
+  "llm",
+  "circuit-breaker",
+  "middleware",
+  "reliability",
+  "api",
+  "decorator"
+]
+
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

logic_fingerprint-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

logic_fingerprint-0.1.0/src/logic_fingerprint/__init__.py

@@ -0,0 +1,2 @@
+from .runtime import build_runtime
+from .protect import protect, create_protector

logic_fingerprint-0.1.0/src/logic_fingerprint/api.py

@@ -0,0 +1,86 @@
+from dataclasses import asdict, is_dataclass
+from fastapi import APIRouter, Response
+from pydantic import BaseModel, Field
+from .models import HandlerRequest, RequestContext
+from .prometheus_metrics import render_prometheus_metrics
+
+class ForceFailRequest(BaseModel):
+    reason: str = "MANUAL_FAIL"
+
+class ExecuteHandlerContextModel(BaseModel):
+    request_id: str | None = None
+    trace_id: str | None = None
+    user_id: str | None = None
+    source: str | None = None
+    timestamp: str | None = None
+    headers: dict = Field(default_factory=dict)
+    metadata: dict = Field(default_factory=dict)
+
+class ExecuteHandlerRequest(BaseModel):
+    handler: str
+    payload: dict = Field(default_factory=dict)
+    context: ExecuteHandlerContextModel = Field(default_factory=ExecuteHandlerContextModel)
+    now: float | None = None
+
+def build_router(runtime: object) -> APIRouter:
+    router = APIRouter()
+    fsm = runtime.fsm
+    metrics = runtime.metrics
+
+    @router.get("/")
+    def root():
+        return {"service": "logic-fingerprint", "state": fsm.state.value, "docs": "/docs"}
+
+    @router.get("/favicon.ico")
+    def favicon():
+        return Response(status_code=204)
+
+    @router.get("/healthz")
+    def healthz():
+        return {"ok": True, "state": fsm.state.value}
+
+    @router.get("/handlers")
+    def handlers():
+        return {"handlers": runtime.handler_registry.names()}
+
+    @router.get("/metrics")
+    def metrics_view():
+        return metrics.snapshot()
+
+    @router.get("/metrics.prom")
+    def metrics_prom():
+        return Response(content=render_prometheus_metrics(metrics, fsm), media_type="text/plain; version=0.0.4")
+
+    @router.post("/force_fail")
+    def force_fail(payload: ForceFailRequest):
+        fsm.record_hard_fail(payload.reason)
+        return {"state": fsm.state.value, "reason": payload.reason}
+
+    @router.post("/move_half_open")
+    def move_half_open():
+        fsm.move_to_half_open()
+        return {"state": fsm.state.value}
+
+    @router.post("/execute_handler")
+    async def execute_handler(payload: ExecuteHandlerRequest):
+        request = HandlerRequest(
+            payload=payload.payload,
+            context=RequestContext(
+                request_id=payload.context.request_id,
+                trace_id=payload.context.trace_id,
+                user_id=payload.context.user_id,
+                source=payload.context.source,
+                timestamp=payload.context.timestamp,
+                headers=payload.context.headers,
+                metadata=payload.context.metadata,
+            ),
+        )
+        outcome = await runtime.middleware.execute_handler_async(payload.handler, request=request, now=payload.now)
+        if outcome.succeeded:
+            result = outcome.result
+            if is_dataclass(result):
+                result = asdict(result)
+            return {"ok": True, "result": result}
+        return {"ok": False, "error": {"code": outcome.error_code, "message": outcome.error_message, "details": outcome.error_details or {}}}
+
+    return router

logic_fingerprint-0.1.0/src/logic_fingerprint/app_factory.py

@@ -0,0 +1,13 @@
+from fastapi import FastAPI
+from .api import build_router
+from .lifespan import build_lifespan
+from .runtime import build_runtime
+
+def create_app() -> FastAPI:
+    runtime = build_runtime()
+    app = FastAPI(title="Logic Fingerprint System", version="1.0.0", lifespan=build_lifespan(runtime, interval_seconds=1.0))
+    app.state.runtime = runtime
+    app.include_router(build_router(runtime))
+    return app
+
+app = create_app()

logic_fingerprint-0.1.0/src/logic_fingerprint/config.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+
+@dataclass(slots=True)
+class ProbeConfig:
+    probe_rate: float = 0.1
+    probe_interval_seconds: float = 10.0
+    consecutive_success_threshold: int = 3
+    total_nodes: int = 1
+    global_fail_threshold: float = 1.0

logic_fingerprint-0.1.0/src/logic_fingerprint/consensus.py

@@ -0,0 +1,11 @@
+class InMemoryConsensusBackend:
+    def __init__(self) -> None:
+        self._failed_nodes: set[str] = set()
+    def mark_failed(self, instance_id: str) -> None:
+        self._failed_nodes.add(instance_id)
+    def clear_failed(self, instance_id: str) -> None:
+        self._failed_nodes.discard(instance_id)
+    def fail_count(self) -> int:
+        return len(self._failed_nodes)
+    def is_failed(self, instance_id: str) -> bool:
+        return instance_id in self._failed_nodes

logic_fingerprint-0.1.0/src/logic_fingerprint/context_builder.py

@@ -0,0 +1,21 @@
+from datetime import datetime, timezone
+from uuid import uuid4
+from .models import HandlerRequest, RequestContext
+
+class ContextBuilder:
+    def __init__(self, default_source: str = "api") -> None:
+        self.default_source = default_source
+    def build_context(self, context: RequestContext | None = None) -> RequestContext:
+        context = context or RequestContext()
+        return RequestContext(
+            request_id=context.request_id or f"req-{uuid4().hex}",
+            trace_id=context.trace_id or f"trace-{uuid4().hex}",
+            user_id=context.user_id,
+            source=context.source or self.default_source,
+            timestamp=context.timestamp or datetime.now(timezone.utc).isoformat(),
+            headers=dict(context.headers),
+            metadata=dict(context.metadata),
+        )
+    def build_request(self, request: HandlerRequest | None = None) -> HandlerRequest:
+        request = request or HandlerRequest()
+        return HandlerRequest(payload=dict(request.payload), context=self.build_context(request.context))

logic_fingerprint-0.1.0/src/logic_fingerprint/errors.py

@@ -0,0 +1,49 @@
+from enum import Enum
+
+class ErrorCode(str, Enum):
+    ERR_TIMEOUT = "ERR_TIMEOUT"
+    ERR_NULL = "ERR_NULL"
+    ERR_NORM = "ERR_NORM"
+    ERR_LOGIC = "ERR_LOGIC"
+    ERR_EXECUTION_BLOCKED = "ERR_EXECUTION_BLOCKED"
+    ERR_UNKNOWN = "ERR_UNKNOWN"
+    ERR_HANDLER_NOT_FOUND = "ERR_HANDLER_NOT_FOUND"
+    ERR_VALIDATION = "ERR_VALIDATION"
+    ERR_OUTPUT_VALIDATION = "ERR_OUTPUT_VALIDATION"
+
+class LogicFingerprintError(Exception):
+    code: ErrorCode = ErrorCode.ERR_UNKNOWN
+    def __init__(self, message: str = "", details: dict | None = None) -> None:
+        super().__init__(message)
+        self.message = message or self.__class__.__name__
+        self.details = details or {}
+
+class TimeoutErrorLF(LogicFingerprintError):
+    code = ErrorCode.ERR_TIMEOUT
+
+class NullResultError(LogicFingerprintError):
+    code = ErrorCode.ERR_NULL
+
+class NormalizationError(LogicFingerprintError):
+    code = ErrorCode.ERR_NORM
+
+class LogicExecutionError(LogicFingerprintError):
+    code = ErrorCode.ERR_LOGIC
+
+class HandlerNotFoundError(LogicFingerprintError):
+    code = ErrorCode.ERR_HANDLER_NOT_FOUND
+
+class ValidationErrorLF(LogicFingerprintError):
+    code = ErrorCode.ERR_VALIDATION
+
+class OutputValidationErrorLF(LogicFingerprintError):
+    code = ErrorCode.ERR_OUTPUT_VALIDATION
+
+def classify_exception(exc: Exception) -> ErrorCode:
+    if isinstance(exc, LogicFingerprintError):
+        return exc.code
+    if isinstance(exc, TimeoutError):
+        return ErrorCode.ERR_TIMEOUT
+    if isinstance(exc, ValueError):
+        return ErrorCode.ERR_NORM
+    return ErrorCode.ERR_UNKNOWN

logic_fingerprint-0.1.0/src/logic_fingerprint/executor.py

@@ -0,0 +1,52 @@
+import inspect
+from dataclasses import dataclass
+from .errors import ErrorCode, NullResultError, classify_exception, LogicFingerprintError
+from .models import ExecutionDecision, ExecutionOutcome, FSMState, ProbeResult
+
+@dataclass(slots=True)
+class LogicFingerprintExecutor:
+    fsm: object
+
+    def _build_decision_from_closed(self):
+        info = self.fsm.before_request()
+        return ExecutionDecision(state=str(info["state"]), allow_request=bool(info["allow_request"]), allow_probe=bool(info["allow_probe"]), global_fail_ratio=float(info["global_fail_ratio"]), external_fail_ratio=float(info["external_fail_ratio"]), is_probe=False)
+    def _build_decision_from_half_open(self, now):
+        info = self.fsm.before_half_open_request(now=now)
+        return ExecutionDecision(state=str(info["state"]), allow_request=bool(info["allow_request"]), allow_probe=bool(info["allow_probe"]), global_fail_ratio=float(info["global_fail_ratio"]), external_fail_ratio=float(info["external_fail_ratio"]), is_probe=bool(info["allow_probe"]))
+    def _blocked_outcome(self, decision):
+        return ExecutionOutcome(decision=decision, executed=False, succeeded=False, state_after=self.fsm.state.value, error_code=ErrorCode.ERR_EXECUTION_BLOCKED.value, error_message="Request blocked by FSM state.")
+    def _success_outcome(self, decision, result):
+        if decision.is_probe:
+            self.fsm.evaluate_probe(ProbeResult(system_success=True, business_success=True))
+        return ExecutionOutcome(decision=decision, executed=True, succeeded=True, state_after=self.fsm.state.value, result=result)
+    def _failure_outcome(self, decision, exc):
+        code = classify_exception(exc)
+        details = exc.details if isinstance(exc, LogicFingerprintError) else {}
+        self.fsm.record_hard_fail(code.value)
+        return ExecutionOutcome(decision=decision, executed=True, succeeded=False, state_after=self.fsm.state.value, error_code=code.value, error_message=str(exc), error_details=details)
+    def execute(self, operation, now=None):
+        decision = self._build_decision_from_half_open(now) if self.fsm.state == FSMState.HALF_OPEN else self._build_decision_from_closed()
+        if not decision.allow_request and not decision.allow_probe:
+            return self._blocked_outcome(decision)
+        try:
+            result = operation()
+            if inspect.isawaitable(result):
+                raise TypeError("Async operation cannot be executed by sync execute(); use execute_async().")
+            if result is None:
+                raise NullResultError("Operation returned None.")
+            return self._success_outcome(decision, result)
+        except Exception as exc:
+            return self._failure_outcome(decision, exc)
+    async def execute_async(self, operation, now=None):
+        decision = self._build_decision_from_half_open(now) if self.fsm.state == FSMState.HALF_OPEN else self._build_decision_from_closed()
+        if not decision.allow_request and not decision.allow_probe:
+            return self._blocked_outcome(decision)
+        try:
+            result = operation()
+            if inspect.isawaitable(result):
+                result = await result
+            if result is None:
+                raise NullResultError("Operation returned None.")
+            return self._success_outcome(decision, result)
+        except Exception as exc:
+            return self._failure_outcome(decision, exc)