fastfence 0.1.1__py3-none-any.whl

fastfence/__init__.py

@@ -0,0 +1 @@
+"""FastFence: trusted policy enforcement outside agent reasoning."""

fastfence/app/factory.py

@@ -0,0 +1,66 @@
+import asyncio
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager, suppress
+
+from fastapi import FastAPI
+
+from fastfence.app.interfaces.http.documents import configure_documents
+from fastfence.app.interfaces.http.ingress import ProtectedRestIngress
+from fastfence.app.interfaces.http.openai import create_router
+from fastfence.app.interfaces.http.routes import configure_http
+from fastfence.modules.control.application.facade import (
+    ControlRuntime,
+    build_runtime,
+)
+from fastfence.modules.control.contracts.ports import ToolsPort
+from fastfence.modules.control.interfaces.mcp.server import create_mcp
+from fastfence.shared.settings.app_settings import AppSettings
+from fastfence.workflows.anonymization import build_anonymization
+
+
+async def watch_config(runtime: ControlRuntime, interval: float) -> None:
+    while True:
+        await asyncio.sleep(interval)
+        await runtime.refresh_config()
+
+
+def create_app(
+    settings: AppSettings | None = None, *, tools: ToolsPort | None = None
+) -> FastAPI:
+    settings = settings or AppSettings.environment()
+    runtime = build_runtime(
+        settings, anonymization=build_anonymization(settings), tools=tools
+    )
+    mcp = create_mcp(runtime, runtime.identities)
+    mcp_app = mcp.http_app(path="/", stateless_http=True, json_response=True)
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        async with mcp_app.lifespan(app):
+            watcher = asyncio.create_task(
+                watch_config(runtime, settings.config_poll_interval),
+                name="fastfence-config-refresh",
+            )
+            try:
+                yield
+            finally:
+                watcher.cancel()
+                with suppress(asyncio.CancelledError):
+                    await watcher
+                await runtime.aclose()
+
+    app = FastAPI(title="FastFence", version="0.1.0", lifespan=lifespan)
+    app.state.engine = runtime.engine
+    app.state.identities = runtime.identities
+    app.state.settings = settings
+    app.state.runtime = runtime
+    app.add_middleware(
+        ProtectedRestIngress,
+        runtime=runtime,
+        management_limit=settings.max_config_source_bytes,
+    )
+    configure_http(app, runtime)
+    configure_documents(app, runtime, settings)
+    app.include_router(create_router(runtime))
+    app.mount("/mcp", mcp_app)
+    return app

fastfence/app/interfaces/cli/bootstrap_config.py

@@ -0,0 +1,78 @@
+"""Initialize reviewed configuration resources without replacing operator files."""
+
+import json
+import os
+import tempfile
+from importlib.resources import files
+from pathlib import Path
+
+import yaml
+
+from fastfence.modules.control.domain.models import Snapshot
+
+
+class ConfigurationInitializationError(ValueError):
+    """A configuration cannot safely be initialized."""
+
+
+def _read_existing(path: Path, maximum: int) -> bytes:
+    with path.open("rb") as stream:
+        content = stream.read(maximum + 1)
+    if len(content) > maximum:
+        raise ConfigurationInitializationError(
+            "Configuration exceeds the configured size limit; existing files were preserved."
+        )
+    return content
+
+
+def _create_exclusive(path: Path, content: bytes) -> None:
+    descriptor, temporary = tempfile.mkstemp(
+        prefix=".initialize-", dir=path.parent
+    )
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        # Publish only a complete file. A concurrent initializer cannot overwrite it.
+        os.link(temporary, path)
+    finally:
+        Path(temporary).unlink(missing_ok=True)
+
+
+def initialize_config(root: Path, *, max_source_bytes: int = 262_144) -> None:
+    """Validate existing configuration and exclusively create missing defaults.
+
+    This works from an installed wheel; a source checkout is not required.
+    Errors deliberately omit the invalid configuration and validation payload.
+    """
+    directory = root / "config"
+    resources = files("fastfence.shared.defaults")
+    contents: dict[str, bytes] = {}
+    missing: list[str] = []
+    for name in ("policy.yaml", "signatures.json"):
+        path = directory / name
+        if path.exists():
+            contents[name] = _read_existing(path, max_source_bytes)
+        else:
+            contents[name] = resources.joinpath(name).read_bytes()
+            missing.append(name)
+        if len(contents[name]) > max_source_bytes:
+            raise ConfigurationInitializationError(
+                "Configuration exceeds the configured size limit; existing files were preserved."
+            )
+    try:
+        Snapshot.model_validate(
+            {
+                "policy": yaml.safe_load(contents["policy.yaml"]),
+                "feed": json.loads(contents["signatures.json"]),
+            }
+        )
+    except (ValueError, yaml.YAMLError, RecursionError):
+        raise ConfigurationInitializationError(
+            "Invalid configuration in config/policy.yaml or config/signatures.json; "
+            "repair those files and rerun fastfence init. Existing files were preserved."
+        ) from None
+    directory.mkdir(parents=True, exist_ok=True)
+    for name in missing:
+        _create_exclusive(directory / name, contents[name])

fastfence/app/interfaces/cli/initialize.py

@@ -0,0 +1,139 @@
+"""Explicit local credential provisioning; repeat runs never rotate secrets."""
+
+import base64
+import hashlib
+import json
+import os
+import secrets
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from fastfence.modules.control.domain.models import Identity
+from fastfence.shared.settings.app_settings import AppSettings
+from fastfence.workflows.anonymization import build_anonymization
+
+
+class InitialRecord(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+    token_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    identity: Identity
+
+
+def _validate_links(records: list[InitialRecord], tokens: dict) -> None:
+    subjects = [record.identity.subject for record in records]
+    if len(set(subjects)) != len(subjects) or set(tokens) != set(subjects):
+        raise ValueError
+    for record in records:
+        token = tokens[record.identity.subject]
+        if not isinstance(token, str) or not token:
+            raise ValueError
+        if hashlib.sha256(token.encode()).hexdigest() != record.token_sha256:
+            raise ValueError
+
+
+def _validate_existing(state: Path) -> bool:
+    identities, credentials = (
+        state / "identities.json",
+        state
+        / (
+            "credentials.json"
+            if (state / "credentials.json").exists()
+            else "demo-tokens.json"
+        ),
+    )
+    if (state / "credentials.json").exists() and (
+        state / "demo-tokens.json"
+    ).exists():
+        raise SystemExit(
+            "Initialization refused: ambiguous credential files. Existing files were preserved."
+        )
+    if not identities.exists() and not credentials.exists():
+        return False
+    try:
+        raw = json.loads(identities.read_text())
+        tokens = json.loads(credentials.read_text())
+        records = [InitialRecord.model_validate(item) for item in raw]
+        if not records or not isinstance(tokens, dict):
+            raise ValueError
+        if len({record.token_sha256 for record in records}) != len(records):
+            raise ValueError
+        _validate_links(records, tokens)
+    except (OSError, ValueError, TypeError, KeyError):
+        raise SystemExit(
+            "Initialization refused: partial or invalid credential state. "
+            "Existing files were preserved. Restore the matching identities.json "
+            "and credentials.json (or legacy demo-tokens.json) backup, or choose a new directory with --state."
+        ) from None
+    return True
+
+
+def _write_private(path: Path, data: object) -> None:
+    descriptor = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    with os.fdopen(descriptor, "w") as file:
+        json.dump(data, file, indent=2)
+        file.write("\n")
+
+
+def initialize(state: Path) -> None:
+    if _validate_existing(state):
+        print(f"Already initialized: {state}. Existing credentials preserved.")
+        return
+    state.mkdir(parents=True, exist_ok=True)
+    state.chmod(0o700)
+    records, tokens = [], {}
+    for subject, tenant, roles, admin in [
+        ("local-agent", "local", ["analyst"], False),
+        ("local-admin", "management", [], True),
+    ]:
+        token = secrets.token_urlsafe(32)
+        tokens[subject] = token
+        records.append(
+            {
+                "token_sha256": hashlib.sha256(token.encode()).hexdigest(),
+                "identity": {
+                    "subject": subject,
+                    "tenant": tenant,
+                    "roles": roles,
+                    "admin": admin,
+                },
+            }
+        )
+    _write_private(state / "identities.json", records)
+    _write_private(state / "credentials.json", tokens)
+    print(
+        f"Initialized {state}. Credentials: {state / 'credentials.json'} (private, gitignored)."
+    )
+    print(
+        "Dashboard: connect local-admin to manage policies; use local-agent to make protected requests."
+    )
+
+
+def initialize_keys(path: Path, key_id: str) -> None:
+    if path.exists():
+        build_anonymization(
+            AppSettings(
+                anonymization_keys_file=path, anonymization_key_id=key_id
+            )
+        ).close()
+        print(f"Anonymization keyring preserved: {path}")
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _write_private(
+        path, {key_id: base64.b64encode(secrets.token_bytes(32)).decode()}
+    )
+    print(f"Private anonymization keyring created: {path} (mode 0600).")
+
+
+def initialize_anonymization(settings: AppSettings) -> None:
+    if settings.anonymization_keys_json is not None:
+        build_anonymization(settings).close()
+        print(
+            "Existing environment anonymization keyring validated and preserved."
+        )
+        return
+    initialize_keys(
+        settings.anonymization_keys_file
+        or settings.state_path / "anonymization-keys.json",
+        settings.anonymization_key_id,
+    )

fastfence/app/interfaces/cli/laya_install.py

@@ -0,0 +1,64 @@
+"""Install the reviewed Laya helpers from a wheel without a source checkout."""
+
+import shutil
+import subprocess
+from importlib.resources import files
+from pathlib import Path
+
+from fastfence.app.interfaces.cli.bootstrap_config import _create_exclusive
+
+LAYA_FILES = (
+    "setup.sh",
+    "semantic_worker.py",
+    "semantic_response.py",
+    "authoring_contracts.py",
+    "policy_generation.py",
+    "draft_policy.py",
+    "author_rule.py",
+    "run_demo.py",
+)
+
+
+def stage_laya(root: Path) -> Path:
+    bundle = files("fastfence.shared").joinpath("laya_bundle")
+    development = Path(__file__).resolve().parents[5] / "integrations/laya"
+    contents = {
+        name: bundle.joinpath(name).read_bytes()
+        if bundle.is_dir()
+        else (development / name).read_bytes()
+        for name in LAYA_FILES
+    }
+    destination = root / "integrations/laya"
+    for name, content in contents.items():
+        path = destination / name
+        if path.is_symlink() or (
+            path.exists() and path.read_bytes() != content
+        ):
+            raise ValueError(
+                "Existing Laya helper files differ from this package; preserve your changes and choose a new FASTFENCE_AUTHORING_ROOT."
+            )
+    destination.mkdir(parents=True, exist_ok=True)
+    for name, content in contents.items():
+        path = destination / name
+        if not path.exists():
+            _create_exclusive(path, content)
+    return destination / "setup.sh"
+
+
+def setup_laya(root: Path) -> None:
+    if any(shutil.which(name) is None for name in ("git", "uv", "sh")):
+        raise SystemExit(
+            "Laya setup requires git, sh and uv. Install Git and run `python -m pip install uv`, then retry `fastfence setup-laya`."
+        )
+    try:
+        script = stage_laya(root)
+    except ValueError as error:
+        raise SystemExit(str(error)) from None
+    result = subprocess.run(["sh", str(script)], cwd=root, check=False)
+    if result.returncode:
+        raise SystemExit(
+            "Laya setup failed; resolve the installer error and retry."
+        )
+    print(
+        "Laya installed. Start Ollama and run `ollama pull qwen3:4b` and `ollama pull qwen3:0.6b`."
+    )

fastfence/app/interfaces/cli/main.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+import uvicorn
+
+from fastfence.app.interfaces.cli.bootstrap_config import initialize_config
+from fastfence.app.interfaces.cli.initialize import (
+    initialize,
+    initialize_anonymization,
+)
+from fastfence.app.interfaces.cli.laya_install import setup_laya
+from fastfence.app.interfaces.cli.ocr_install import setup_ocr
+from fastfence.app.interfaces.cli.startup import (
+    doctor,
+    preflight,
+    startup_error,
+)
+from fastfence.shared.settings.app_settings import AppSettings
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="FastFence AI Control Layer")
+    parser.add_argument(
+        "command",
+        choices=["init", "serve", "doctor", "setup-laya", "setup-ocr"],
+    )
+    parser.add_argument(
+        "--state", help="Private state directory (overrides .env)"
+    )
+    parser.add_argument(
+        "--anonymization",
+        action="store_true",
+        help="Provision a private anonymization keyring during init",
+    )
+    parser.add_argument(
+        "--full",
+        action="store_true",
+        help="Doctor: require Laya, OCR, Qwen and anonymization readiness",
+    )
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8000)
+    args = parser.parse_args()
+    previous_state = os.environ.get("FASTFENCE_STATE")
+    if args.state is not None:
+        os.environ["FASTFENCE_STATE"] = str(Path(args.state).resolve())
+    try:
+        settings = AppSettings.environment()
+        if args.command == "init":
+            initialize_config(
+                settings.root, max_source_bytes=settings.max_config_source_bytes
+            )
+            initialize(settings.state_path)
+            if args.anonymization:
+                initialize_anonymization(settings)
+        elif args.command == "setup-laya":
+            setup_laya(settings.authoring_root or settings.root)
+        elif args.command == "setup-ocr":
+            setup_ocr(settings.state_path)
+        elif args.command == "doctor":
+            doctor(settings, full=args.full)
+        else:
+            preflight(settings)
+            uvicorn.run(
+                "fastfence.app.factory:create_app",
+                factory=True,
+                host=args.host,
+                port=args.port,
+            )
+    except (OSError, ValueError, TypeError, KeyError):
+        raise SystemExit(startup_error()) from None
+    finally:
+        if previous_state is None:
+            os.environ.pop("FASTFENCE_STATE", None)
+        else:
+            os.environ["FASTFENCE_STATE"] = previous_state
+
+
+if __name__ == "__main__":
+    main()

fastfence/app/interfaces/cli/ocr_install.py

@@ -0,0 +1,62 @@
+"""Install hash-locked OCR dependencies for an installed wheel."""
+
+import os
+import shutil
+import subprocess
+from importlib.resources import as_file, files
+from pathlib import Path
+
+
+def _run(command: list[str], environment: dict[str, str]) -> None:
+    if subprocess.run(command, env=environment, check=False).returncode:
+        raise SystemExit(
+            "OCR setup failed; resolve the installer error and retry."
+        )
+
+
+def setup_ocr(state: Path) -> None:
+    if shutil.which("uv") is None:
+        raise SystemExit(
+            "OCR setup requires uv. Run `python -m pip install uv`, then retry `fastfence setup-ocr`."
+        )
+    private = state / "private"
+    private.mkdir(parents=True, exist_ok=True, mode=0o700)
+    python = private / "ocr-env/bin/python"
+    models = private / "ocr-models"
+    environment = dict(os.environ)
+    environment["PYTHONPATH"] = str(Path(__file__).resolve().parents[4])
+    environment["PYTHONDONTWRITEBYTECODE"] = "1"
+    if not python.is_file():
+        _run(
+            ["uv", "venv", "--python", "3.12", str(python.parent.parent)],
+            environment,
+        )
+    requirements = files("fastfence.shared.defaults").joinpath(
+        "ocr-requirements.txt"
+    )
+    with as_file(requirements) as source:
+        _run(
+            [
+                "uv",
+                "pip",
+                "install",
+                "--python",
+                str(python),
+                "--require-hashes",
+                "-r",
+                str(source),
+            ],
+            environment,
+        )
+    _run(
+        [
+            str(python),
+            "-m",
+            "fastfence.modules.ocr.persistence.bootstrap",
+            str(models),
+        ],
+        environment,
+    )
+    print(
+        "OCR dependencies and local mobile models installed. Restart FastFence to detect the configured state directory's OCR environment."
+    )

fastfence/app/interfaces/cli/startup.py

@@ -0,0 +1,178 @@
+"""Read-only readiness checks. Diagnostic output excludes private input values."""
+
+import os
+import shlex
+import subprocess
+from pathlib import Path
+
+import httpx
+
+from fastfence.modules.control.application.facade import build_runtime
+from fastfence.shared.settings.app_settings import AppSettings
+from fastfence.workflows.anonymization import build_anonymization
+
+
+def startup_error() -> str:
+    return (
+        "FastFence startup/configuration failed. No credentials were changed. "
+        "Run `fastfence doctor` to check prerequisites. "
+        "Check private identity/key configuration and config/policy.yaml; "
+        "validation input is omitted to protect secrets."
+    )
+
+
+def preflight(settings: AppSettings) -> None:
+    if settings.identity_config_json is None:
+        path = (
+            settings.identity_config_file
+            or settings.state_path / "identities.json"
+        )
+        if not path.is_file():
+            command = f"fastfence init --state {shlex.quote(str(settings.state_path))} --anonymization"
+            hint = (
+                "Provision FASTFENCE_IDENTITY_CONFIG_FILE at the configured location."
+                if settings.identity_config_file
+                else f"Initialize local credentials first: {command}"
+            )
+            raise SystemExit(
+                f"FastFence cannot start: identity configuration is missing. {hint}"
+            )
+    for name in ("policy.yaml", "signatures.json"):
+        if not (settings.root / "config" / name).is_file():
+            raise SystemExit(
+                f"FastFence cannot start: config/{name} is missing. Run from the repository root or set FASTFENCE_ROOT."
+            )
+    runtime = build_runtime(
+        settings, anonymization=build_anonymization(settings)
+    )
+    try:
+        snapshot = runtime.snapshot()
+        if (
+            snapshot.policy.anonymization.enabled
+            and runtime.engine.anonymization is not None
+        ):
+            if settings.anonymization_keys_json is None:
+                key_file = (
+                    settings.anonymization_keys_file
+                    or settings.state_path / "anonymization-keys.json"
+                )
+                if not key_file.is_file():
+                    raise SystemExit(
+                        "Anonymization is enabled but no keyring is configured. Run `fastfence init --anonymization` before serving."
+                    )
+    finally:
+        runtime.close()
+
+
+def _python_imports(interpreter: Path, modules: str) -> bool:
+    if not interpreter.is_file() or not os.access(interpreter, os.X_OK):
+        return False
+    try:
+        result = subprocess.run(
+            [str(interpreter), "-B", "-c", modules],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            timeout=30,
+            check=False,
+        )
+        return result.returncode == 0
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+
+
+def _ocr_ready(settings: AppSettings) -> bool:
+    if settings.ocr_python is None or settings.ocr_models is None:
+        return False
+    names = (
+        "PP-LCNet_x1_0_doc_ori",
+        "PP-OCRv5_mobile_det",
+        "latin_PP-OCRv5_mobile_rec",
+    )
+    if not all(
+        (settings.ocr_models / name / "inference.json").is_file()
+        for name in names
+    ):
+        return False
+    return _python_imports(
+        settings.ocr_python, "import paddle, paddleocr, pypdfium2, PIL"
+    )
+
+
+def _laya_ready(settings: AppSettings) -> bool:
+    root = settings.authoring_root or settings.root
+    paths = [
+        root / "integrations/laya/draft_policy.py",
+        root / "integrations/laya/semantic_worker.py",
+        root / "state/laya/upstream/engine",
+    ]
+    return all(path.exists() for path in paths) and _python_imports(
+        root / "state/laya/venv/bin/python",
+        "import sys; "
+        f"sys.path[:0] = {[str(root / 'integrations/laya'), str(root / 'state/laya/upstream/engine')]!r}; "
+        "import semantic_worker, litellm; "
+        "from laya.llm import client; assert callable(client.llm_call)",
+    )
+
+
+def _ollama_ready(settings: AppSettings) -> bool:
+    try:
+        with httpx.Client(timeout=3, trust_env=False) as client:
+            response = client.get(settings.ollama_url.rstrip("/") + "/api/tags")
+            response.raise_for_status()
+            names = {item["name"] for item in response.json()["models"]}
+        return {"qwen3:0.6b", "qwen3:4b"} <= names
+    except (httpx.HTTPError, ValueError, KeyError, TypeError):
+        return False
+
+
+def doctor(settings: AppSettings, *, full: bool = False) -> None:
+    try:
+        preflight(settings)
+    except SystemExit as error:
+        print(f"FAIL core: {error}")
+        raise SystemExit(1) from None
+    print(
+        "OK core: identities, policy, signatures and configured keyring validated."
+    )
+    if not full:
+        print(
+            "Run `fastfence doctor --full` to check optional feature prerequisites."
+        )
+        return
+    checks = [
+        (
+            "Laya authoring and text-assessment installation",
+            _laya_ready(settings),
+            "bash integrations/laya/setup.sh",
+        ),
+        (
+            "OCR interpreter and model files",
+            _ocr_ready(settings),
+            "bash scripts/setup-ocr.sh",
+        ),
+        (
+            "Qwen model availability",
+            _ollama_ready(settings),
+            "ollama serve; ollama pull qwen3:0.6b; ollama pull qwen3:4b",
+        ),
+        (
+            "anonymization keyring",
+            settings.anonymization_keys_json is not None
+            or (
+                settings.anonymization_keys_file
+                or settings.state_path / "anonymization-keys.json"
+            ).is_file(),
+            "fastfence init --anonymization",
+        ),
+    ]
+    for label, ready, fix in checks:
+        print(
+            f"{'OK' if ready else 'FAIL'} {label}"
+            + ("" if ready else f": {fix}")
+        )
+    if not all(ready for _, ready, _ in checks):
+        raise SystemExit(1)
+    print(
+        "Prerequisite checks passed. Run the manual scenarios to verify end-to-end model behavior."
+    )