logicfp 2.1.0__tar.gz

logicfp-2.1.0/MANIFEST.in

@@ -0,0 +1,17 @@
+prune analysis
+prune demo
+prune documents
+prune examples
+prune src/logicfp.egg-info
+prune static
+prune tests
+
+exclude repomix-output.xml
+exclude requirements.txt
+exclude uv.lock
+
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude *.sqlite
+global-exclude *.egg-info
+global-exclude .pytest_tmp*

logicfp-2.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: logicfp
+Version: 2.1.0
+Summary: logicfp protection runtime and HTTP service
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi==0.135.2
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: uvicorn==0.42.0
+Provides-Extra: release
+Requires-Dist: build>=2.0.0; extra == "release"
+Requires-Dist: twine>=6.1.0; extra == "release"
+
+# Logic Fingerprint (logicfp)
+
+`logicfp` is a Python protection library for wrapping function boundaries with circuit-breaker style control.
+
+Developer documentation lives in [README.developer.md](D:/workspace/python/logic_fingerprint_ai/README.developer.md).
+
+## Install
+
+```bash
+pip install logicfp
+```
+
+## Quick Start
+
+```python
+from logicfp import protect
+
+
+@protect(simple=False)
+def call_model(request):
+    return {"answer": request.payload["text"].upper()}
+
+
+result = call_model(payload={"text": "hello"})
+```
+
+Use `@protect()` when you want the simplest user-mode entrypoint.
+Use `create_protector()` when you need more than one protector instance.
+Use `logicfp.user_mode` when you want explicit user-mode types like `ProtectRuntimeError`.
+
+## Minimal Config
+
+Put your project config at:
+
+```text
+your_project/config/config.yaml
+```
+
+```yaml
+logicfp:
+  instance_id: decorator-node
+  default_source: user_function
+  backend_type: memory
+```
+
+Use `logicfp:` as the main YAML section name. Older `logic_fingerprint:` configs are still accepted for compatibility.
+
+## Learn More
+
+- Quick user-mode guide: [documents/Tutorial/用户模式快速接入.md](D:/workspace/python/logic_fingerprint_ai/documents/Tutorial/用户模式快速接入.md)
+- User mode: [documents/Tutorial/用户模式示例.md](D:/workspace/python/logic_fingerprint_ai/documents/Tutorial/用户模式示例.md)
+- Mode guide: [documents/Tutorial/protect 的用户模式与工程模式.md](D:/workspace/python/logic_fingerprint_ai/documents/Tutorial/protect%20的用户模式与工程模式.md)
+- Optional engineering mode: [documents/Tutorial/工程模式示例.md](D:/workspace/python/logic_fingerprint_ai/documents/Tutorial/工程模式示例.md)

logicfp-2.1.0/README.md

@@ -0,0 +1,53 @@
+# Logic Fingerprint (logicfp)
+
+`logicfp` is a Python protection library for wrapping function boundaries with circuit-breaker style control.
+
+Developer documentation lives in [README.developer.md](D:/workspace/python/logic_fingerprint_ai/README.developer.md).
+
+## Install
+
+```bash
+pip install logicfp
+```
+
+## Quick Start
+
+```python
+from logicfp import protect
+
+
+@protect(simple=False)
+def call_model(request):
+    return {"answer": request.payload["text"].upper()}
+
+
+result = call_model(payload={"text": "hello"})
+```
+
+Use `@protect()` when you want the simplest user-mode entrypoint.
+Use `create_protector()` when you need more than one protector instance.
+Use `logicfp.user_mode` when you want explicit user-mode types like `ProtectRuntimeError`.
+
+## Minimal Config
+
+Put your project config at:
+
+```text
+your_project/config/config.yaml
+```
+
+```yaml
+logicfp:
+  instance_id: decorator-node
+  default_source: user_function
+  backend_type: memory
+```
+
+Use `logicfp:` as the main YAML section name. Older `logic_fingerprint:` configs are still accepted for compatibility.
+
+## Learn More
+
+- Quick user-mode guide: [documents/Tutorial/用户模式快速接入.md](D:/workspace/python/logic_fingerprint_ai/documents/Tutorial/用户模式快速接入.md)
+- User mode: [documents/Tutorial/用户模式示例.md](D:/workspace/python/logic_fingerprint_ai/documents/Tutorial/用户模式示例.md)
+- Mode guide: [documents/Tutorial/protect 的用户模式与工程模式.md](D:/workspace/python/logic_fingerprint_ai/documents/Tutorial/protect%20的用户模式与工程模式.md)
+- Optional engineering mode: [documents/Tutorial/工程模式示例.md](D:/workspace/python/logic_fingerprint_ai/documents/Tutorial/工程模式示例.md)

logicfp-2.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "logicfp"
+dynamic = ["version"]
+description = "logicfp protection runtime and HTTP service"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi==0.135.2",
+    "pydantic==2.12.5",
+    "uvicorn==0.42.0",
+]
+
+[project.optional-dependencies]
+release = [
+    "build>=2.0.0",
+    "twine>=6.1.0",
+]
+
+[project.scripts]
+logicfp = "logicfp.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["logicfp*"]
+
+[tool.setuptools.dynamic]
+version = {attr = "logicfp._version.__version__"}

logicfp-2.1.0/setup.cfg

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

logicfp-2.1.0/src/logicfp/__init__.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ._version import __version__
+
+__all__ = [
+    "protect",
+    "create_protector",
+]
+
+_ENGINEERING_EXPORTS = {
+    "assemble_runtime",
+    "build_demo_runtime",
+    "build_production_runtime",
+    "build_runtime",
+    "create_http_app",
+    "create_app",
+    "create_demo_app",
+}
+
+
+def protect(*args: Any, **kwargs: Any):
+    from .decorator import protect as _protect
+
+    return _protect(*args, **kwargs)
+
+
+def create_protector(*args: Any, **kwargs: Any):
+    from .decorator import create_protector as _create_protector
+
+    return _create_protector(*args, **kwargs)
+
+
+def __getattr__(name: str):
+    if name in _ENGINEERING_EXPORTS:
+        raise AttributeError(
+            f"'logicfp.{name}' is not exported from the package root. "
+            "Import it from 'logicfp.engineering' instead."
+        )
+    raise AttributeError(f"module 'logicfp' has no attribute '{name}'")

logicfp-2.1.0/src/logicfp/_version.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+__version__ = "2.1.0"

logicfp-2.1.0/src/logicfp/app_factory.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal
+
+from fastapi import FastAPI
+from fastapi.openapi.docs import (
+    get_swagger_ui_html,
+    get_swagger_ui_oauth2_redirect_html,
+)
+from fastapi.staticfiles import StaticFiles
+
+from ._version import __version__
+from .router import build_router
+from .lifespan import build_lifespan
+from .runtime import (
+    LogicFingerprintRuntime,
+    build_demo_runtime,
+    build_production_runtime,
+)
+
+
+DOCS_STATIC_DIR = Path(__file__).resolve().parents[2] / "static" / "dist"
+HTTPAppMode = Literal["production", "demo"]
+
+
+def _create_app_from_runtime(runtime: LogicFingerprintRuntime) -> FastAPI:
+    app = FastAPI(
+        title="logicfp",
+        version=__version__,
+        lifespan=build_lifespan(runtime, interval_seconds=1.0),
+        docs_url=None,
+        redoc_url=None,
+    )
+    app.state.runtime = runtime
+    app.state.runtime_config = runtime.config
+    app.state.runtime_settings = runtime.settings
+    if DOCS_STATIC_DIR.exists():
+        app.mount(
+            "/static-docs",
+            StaticFiles(directory=DOCS_STATIC_DIR),
+            name="static-docs",
+        )
+
+    @app.get("/docs", include_in_schema=False)
+    def swagger_ui_html():
+        return get_swagger_ui_html(
+            openapi_url=app.openapi_url,
+            title=f"{app.title} - Swagger UI",
+            oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
+            swagger_js_url="/static-docs/swagger-ui-bundle.js",
+            swagger_css_url="/static-docs/swagger-ui.css",
+            swagger_favicon_url="/static-docs/favicon-32x32.png",
+            swagger_ui_parameters={
+                "presets": [
+                    "SwaggerUIBundle.presets.apis",
+                    "SwaggerUIStandalonePreset",
+                ],
+            },
+        )
+
+    @app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
+    def swagger_ui_redirect():
+        return get_swagger_ui_oauth2_redirect_html()
+
+    app.include_router(build_router(runtime))
+    return app
+
+
+def create_http_app(
+    *,
+    mode: HTTPAppMode = "production",
+    runtime: LogicFingerprintRuntime | None = None,
+    runtime_kwargs: dict[str, Any] | None = None,
+) -> FastAPI:
+    if runtime is not None and runtime_kwargs is not None:
+        raise ValueError("Pass either 'runtime' or 'runtime_kwargs', not both.")
+
+    if runtime is None:
+        runtime_builders = {
+            "production": build_production_runtime,
+            "demo": build_demo_runtime,
+        }
+        try:
+            runtime_builder = runtime_builders[mode]
+        except KeyError as exc:
+            raise ValueError(f"Unsupported HTTP app mode: {mode}") from exc
+        runtime = runtime_builder(**(runtime_kwargs or {}))
+
+    return _create_app_from_runtime(runtime)
+
+
+def create_app(
+    *,
+    runtime: LogicFingerprintRuntime | None = None,
+    runtime_kwargs: dict[str, Any] | None = None,
+) -> FastAPI:
+    return create_http_app(
+        mode="production",
+        runtime=runtime,
+        runtime_kwargs=runtime_kwargs,
+    )
+
+
+def create_demo_app(
+    *,
+    runtime: LogicFingerprintRuntime | None = None,
+    runtime_kwargs: dict[str, Any] | None = None,
+) -> FastAPI:
+    return create_http_app(
+        mode="demo",
+        runtime=runtime,
+        runtime_kwargs=runtime_kwargs,
+    )
+
+
+app = create_http_app()
+

logicfp-2.1.0/src/logicfp/application/__init__.py

@@ -0,0 +1,3 @@
+from .context_builder import ContextBuilder
+from .metrics import InMemoryMetrics
+from .validator import validate_input, validate_output

logicfp-2.1.0/src/logicfp/application/context_builder.py

@@ -0,0 +1,22 @@
+from datetime import datetime, timezone
+from uuid import uuid4
+from ..domain.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))
+

logicfp-2.1.0/src/logicfp/application/metrics.py

@@ -0,0 +1,15 @@
+from dataclasses import dataclass, asdict
+
+@dataclass(slots=True)
+class InMemoryMetrics:
+    total_requests: int = 0
+    blocked_requests: int = 0
+    probe_requests: int = 0
+    success_requests: int = 0
+    failed_requests: int = 0
+    def record_total(self): self.total_requests += 1
+    def record_blocked(self): self.blocked_requests += 1
+    def record_probe(self): self.probe_requests += 1
+    def record_success(self): self.success_requests += 1
+    def record_failure(self): self.failed_requests += 1
+    def snapshot(self): return asdict(self)

logicfp-2.1.0/src/logicfp/application/validator.py

@@ -0,0 +1,75 @@
+from dataclasses import asdict, is_dataclass
+from typing import Any
+
+from pydantic import BaseModel, ValidationError
+
+from ..domain.errors import OutputValidationErrorLF, ValidationErrorLF
+from ..infra.logging.event_logger import LogEvent
+
+
+def validate_input(
+    payload: dict[str, Any],
+    model: type[BaseModel] | None,
+    *,
+    event_logger=None,
+    handler: str | None = None,
+    request_id: str | None = None,
+    trace_id: str | None = None,
+) -> dict[str, Any]:
+    if model is None:
+        return payload
+
+    try:
+        parsed = model.model_validate(payload)
+        return parsed.model_dump()
+    except ValidationError as exc:
+        if event_logger is not None:
+            event_logger.emit(LogEvent(
+                event="input_validation_failed",
+                handler=handler,
+                request_id=request_id,
+                trace_id=trace_id,
+                error_code="ERR_VALIDATION",
+                message="Input validation failed.",
+                extra={"errors": exc.errors()},
+            ))
+        raise ValidationErrorLF(
+            "Input validation failed.",
+            details={"errors": exc.errors()},
+        ) from exc
+
+
+def validate_output(
+    result: Any,
+    model: type[BaseModel] | None,
+    *,
+    event_logger=None,
+    handler: str | None = None,
+    request_id: str | None = None,
+    trace_id: str | None = None,
+) -> Any:
+    if model is None:
+        return result
+
+    raw = result
+    if is_dataclass(result):
+        raw = asdict(result)
+
+    try:
+        parsed = model.model_validate(raw)
+        return parsed.model_dump()
+    except ValidationError as exc:
+        if event_logger is not None:
+            event_logger.emit(LogEvent(
+                event="output_validation_failed",
+                handler=handler,
+                request_id=request_id,
+                trace_id=trace_id,
+                error_code="ERR_OUTPUT_VALIDATION",
+                message="Output validation failed.",
+                extra={"errors": exc.errors()},
+            ))
+        raise OutputValidationErrorLF(
+            "Output validation failed.",
+            details={"errors": exc.errors()},
+        ) from exc

logicfp-2.1.0/src/logicfp/cli.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import argparse
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Sequence
+
+import uvicorn
+
+from .config import DEFAULT_CONFIG_FILE_NAME
+from .config.yaml_support import load_simple_yaml_file, parse_simple_yaml
+from .engineering import create_http_app
+
+
+CLI_CONFIG_FILENAMES = (DEFAULT_CONFIG_FILE_NAME,)
+CONFIG_SECTION_NAMES = ("logicfp", "logic_fingerprint", "logicfingerprint")
+
+RUNTIME_KWARG_KEYS = (
+    "instance_id",
+    "default_source",
+    "backend_type",
+    "handler_registrars",
+    "redis_url",
+    "redis_decode_responses",
+    "redis_key",
+    "redis_key_prefix",
+    "redis_ttl_seconds",
+    "probe_rate",
+    "probe_interval_seconds",
+    "consecutive_success_threshold",
+    "total_nodes",
+    "global_fail_threshold",
+)
+
+
+@dataclass(slots=True)
+class StartConfig:
+    host: str = "0.0.0.0"
+    port: int = 8000
+    demo: bool = False
+    config_path: Path | None = None
+    runtime_kwargs: dict[str, Any] = field(default_factory=dict)
+
+def _iter_project_config_candidates(start_dir: Path) -> list[Path]:
+    candidates: list[Path] = []
+    for directory in (start_dir, *start_dir.parents):
+        for filename in CLI_CONFIG_FILENAMES:
+            candidates.append(directory / "config" / filename)
+        for filename in CLI_CONFIG_FILENAMES:
+            candidates.append(directory / filename)
+    return candidates
+
+
+def _iter_system_config_dirs() -> list[Path]:
+    system_dirs = [
+        Path("/etc/logicfp"),
+        Path("/etc/logic_fingerprint"),
+        Path("/etc/logicfingerprint"),
+    ]
+
+    for env_name in ("PROGRAMDATA", "APPDATA", "LOCALAPPDATA"):
+        value = os.getenv(env_name)
+        if not value:
+            continue
+        base_dir = Path(value)
+        system_dirs.append(base_dir / "logicfp")
+        system_dirs.append(base_dir / "logic_fingerprint")
+        system_dirs.append(base_dir / "logicfingerprint")
+
+    return system_dirs
+
+
+def discover_cli_config_path(
+    explicit_path: str | Path | None = None,
+    *,
+    start_dir: str | Path | None = None,
+    system_dirs: Sequence[Path] | None = None,
+) -> Path | None:
+    if explicit_path is not None:
+        resolved = Path(explicit_path).expanduser()
+        if not resolved.is_absolute():
+            resolved = (Path.cwd() / resolved).resolve()
+        if not resolved.is_file():
+            raise FileNotFoundError(f"CLI config file not found: {resolved}")
+        return resolved
+
+    current_dir = Path(start_dir or Path.cwd()).resolve()
+    for candidate in _iter_project_config_candidates(current_dir):
+        if candidate.is_file():
+            return candidate.resolve()
+
+    for system_dir in system_dirs or _iter_system_config_dirs():
+        if not system_dir.is_dir():
+            continue
+        for filename in CLI_CONFIG_FILENAMES:
+            candidate = system_dir / filename
+            if candidate.is_file():
+                return candidate.resolve()
+
+    return None
+
+
+def load_cli_config(path: Path | None) -> dict[str, Any]:
+    return load_simple_yaml_file(path)
+
+
+def _read_mapping(data: dict[str, Any], key: str) -> dict[str, Any]:
+    value = data.get(key, {})
+    if not isinstance(value, dict):
+        raise ValueError(f"Expected '{key}' to be a mapping in CLI config.")
+    return value
+
+
+def _normalize_runtime_kwargs(data: dict[str, Any]) -> dict[str, Any]:
+    runtime_kwargs: dict[str, Any] = {}
+    logicfp_config: dict[str, Any] = {}
+
+    for section_name in CONFIG_SECTION_NAMES:
+        value = data.get(section_name)
+        if value is None:
+            continue
+        if not isinstance(value, dict):
+            raise ValueError(f"Expected '{section_name}' to be a mapping in CLI config.")
+        logicfp_config = value
+        break
+
+    for key in RUNTIME_KWARG_KEYS:
+        value = logicfp_config.get(key)
+        if value is None and key in data:
+            value = data[key]
+        if value is None:
+            continue
+        if key == "handler_registrars":
+            if isinstance(value, list):
+                value = tuple(str(item) for item in value)
+            elif isinstance(value, str):
+                value = tuple(item.strip() for item in value.split(",") if item.strip())
+        runtime_kwargs[key] = value
+
+    return runtime_kwargs
+
+
+def load_start_config(
+    *,
+    config_path: Path | None,
+    port_override: int | None = None,
+    host_override: str | None = None,
+    demo_override: bool = False,
+) -> StartConfig:
+    data = load_cli_config(config_path)
+    server = _read_mapping(data, "server")
+    app = _read_mapping(data, "app")
+
+    host = host_override or str(server.get("host", "0.0.0.0"))
+    port = port_override if port_override is not None else int(server.get("port", 8000))
+    demo = demo_override or bool(app.get("demo", data.get("demo", False)))
+
+    return StartConfig(
+        host=host,
+        port=port,
+        demo=demo,
+        config_path=config_path,
+        runtime_kwargs={
+            **({"config_file": str(config_path)} if config_path is not None else {}),
+            **_normalize_runtime_kwargs(data),
+        },
+    )
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="logicfp")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    start_parser = subparsers.add_parser("start", help="Start the HTTP service.")
+    start_parser.add_argument("--host", help="Bind host. Defaults to config or 0.0.0.0.")
+    start_parser.add_argument(
+        "--port",
+        type=int,
+        help="Bind port. Defaults to config or 8000.",
+    )
+    start_parser.add_argument(
+        "--config",
+        help="Path to CLI YAML config. Explicit path has the highest priority.",
+    )
+    start_parser.add_argument(
+        "--demo",
+        action="store_true",
+        help="Start in demo mode.",
+    )
+    return parser
+
+
+def start_command(args: argparse.Namespace) -> int:
+    config_path = discover_cli_config_path(args.config)
+    start_config = load_start_config(
+        config_path=config_path,
+        port_override=args.port,
+        host_override=args.host,
+        demo_override=args.demo,
+    )
+
+    if start_config.config_path is not None:
+        print(f"Using CLI config: {start_config.config_path}")
+
+    mode = "demo" if start_config.demo else "production"
+    print(
+        f"Starting logicfp HTTP service on "
+        f"{start_config.host}:{start_config.port} ({mode})"
+    )
+
+    app = create_http_app(
+        mode="demo" if start_config.demo else "production",
+        runtime_kwargs=start_config.runtime_kwargs,
+    )
+    uvicorn.run(app, host=start_config.host, port=start_config.port)
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "start":
+        return start_command(args)
+
+    parser.error(f"Unsupported command: {args.command}")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())