Metadata-Version: 2.5
Name: fastfence
Version: 0.1.2
Summary: A policy gateway for agent tools, resources, and local LLMs
Project-URL: Homepage, https://fastfence.dev
Project-URL: Documentation, https://fastfence.dev
Project-URL: Repository, https://github.com/llama-lovers/HackYeah2026-challenge-second
Project-URL: Issues, https://github.com/llama-lovers/HackYeah2026-challenge-second/issues
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai,gateway,mcp,privacy,security
Requires-Python: <3.13,>=3.12
Requires-Dist: cryptography<51,>=46
Requires-Dist: detect-secrets==1.5.0
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: fastmcp<3,>=2.12
Requires-Dist: google-re2>=1.1.20251105
Requires-Dist: httpx<1,>=0.28
Requires-Dist: pydantic-settings<3,>=2.10
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: pyyaml<7,>=6
Requires-Dist: uvicorn<1,>=0.34
Provides-Extra: ocr
Requires-Dist: paddleocr==3.4.0; extra == 'ocr'
Requires-Dist: paddlepaddle==3.3.0; extra == 'ocr'
Requires-Dist: pillow==12.3.0; extra == 'ocr'
Requires-Dist: pypdfium2==5.13.0; extra == 'ocr'
Description-Content-Type: text/markdown

# FastFence

**Security policies between your agents and their models or tools.**

FastFence is a local AI control layer with authenticated HTTP, OpenAI-compatible
and MCP interfaces. It combines deterministic rules with real Laya/Qwen text
assessment, applies input and output controls, reserves per-identity resource
budgets, and records sanitized decisions. The management console lets you review
policy changes, test requests and inspect activity.

[Documentation](https://fastfence.dev/) · [Getting started](https://fastfence.dev/getting-started/) ·
[Manual testing](https://fastfence.dev/manual-testing/) · [API reference](https://fastfence.dev/integration-reference/)

## Run locally

Requirements: macOS or Linux, Python 3.12 and a running [Ollama](https://ollama.com/) service. Git and `sh` are needed by the installer for the pinned external Laya engine; no FastFence checkout is needed.

```sh
mkdir fastfence-local
cd fastfence-local
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install fastfence uv
fastfence init --anonymization
fastfence setup-laya
ollama pull qwen3:4b
ollama pull qwen3:0.6b
fastfence doctor
fastfence serve
```

Open **http://127.0.0.1:8000**, then **Connection**. Use `local-admin` from
`state/credentials.json` to manage policies and `local-agent` to make protected
requests. Tokens are randomly generated, private, and kept only in browser page
memory after you enter them. Management credentials cannot invoke agent operations.

The default policy uses **Laya with Qwen3:4b to assess input and output text**;
Qwen3:0.6b is the separate protected completion model. Missing or failed assessment
blocks the request. Nothing silently substitutes a deterministic-only classifier.
Model assessment adds inference latency; local rules run before it.

For OCR of images and multipage PDFs:

```sh
fastfence setup-ocr
fastfence doctor --full
```

Restart after installing optional components or changing `.env`. OCR converts
attachments into inspected Markdown; it does not modify image or PDF pixels.

## Make a protected request

This reads your local agent credential without writing it into shell history:

```sh
python - <<'PY'
import json
from pathlib import Path
import httpx

credentials = json.loads(Path("state/credentials.json").read_text())
response = httpx.post(
    "http://127.0.0.1:8000/api/models/complete",
    headers={"Authorization": "Bearer " + credentials["local-agent"]},
    json={"model": "qwen3:0.6b", "prompt": "Hello", "max_output_tokens": 64},
    timeout=120,
)
response.raise_for_status()
print(response.json())
PY
```

The result includes the decision, reason, request ID, active policy version,
semantic provider/score and whether the completion model ran. Find that request
in **Activity**. MCP clients connect to `http://127.0.0.1:8000/mcp/`; OpenAI clients
use `http://127.0.0.1:8000/v1` with the same agent token. See [integration examples](https://fastfence.dev/integrations/).

## Change a policy

1. Open **Policies** and edit configuration or describe a rule in your own words.
2. For a Laya-authored rule, inspect its scope, proposed changes and generated tests.
3. Review the diff, run the tests and activate the reviewed version.
4. Try your own inputs in **Test requests** and inspect the recorded decisions.

Laya has two roles: it drafts reviewable deterministic rules and assesses actual
request/response text when `semantic.provider: laya` is active. Trusted natural-language
assessment instructions belong in `semantic.instructions`. A precise restriction
such as forbidden letters should use a deterministic text rule; model judgments
are approximate and need evaluation for your policy.

The active policy is `config/policy.yaml`; valid higher versions hot-reload without
restarting. `.env` contains deployment settings. Reviewed generated tests are saved
in `config/policy-tests.yaml`. Invalid updates retain the last valid snapshot.

## Connect business tools

The product includes **no simulated business handlers**. Implement `ToolsPort`,
inject the adapter with `create_app(settings, tools=adapter)`, and allowlist its
operations and roles in policy. An allowlist without a connected adapter fails closed.

[The opt-in business-tools example](https://github.com/llama-lovers/HackYeah2026-challenge-second/tree/main/examples/business_tools) runs simulated
search, tenant memory and payment preparation in a separate server and state directory.
It illustrates adapter composition and does not handle real payments.

## Update and verify

Stop the gateway, activate its virtual environment, then run:

```sh
python -m pip install --upgrade fastfence
fastfence doctor
fastfence serve
```

Reload the browser. Your working directory's configuration and private state are independent of the installed package; preserve and back them up. Initialization is repeatable and retains valid existing credentials and keys.

Download [runnable examples](https://fastfence.dev/downloads/fastfence-examples.zip), extract them into `examples/` in your installation directory, and run `python examples/protected_request.py --prompt 'Hello'`. The documentation embeds the complete source for REST, named Laya policies, FastMCP, OpenAI SDK and public/private-key anonymization.

Repository development and automated suite instructions belong in [Contributing](https://fastfence.dev/contributing/). For product verification follow [Manual testing](https://fastfence.dev/manual-testing/).

## Operating scope

Budgets and audit retention are bounded, in-memory and per process. Restarting clears
them; replicas do not share a global quota. Identity configuration and optional
anonymization keys are startup inputs, not a conversation database. Reversible
anonymization requires an intact authenticated token, the correct key and explicit
restoration permission. Keep keys and credentials private and backed up.

Model judgments can miss attacks or block legitimate text. Deterministic checks cover
specific configured patterns, permissions and limits, not universal attack detection.
Irreversible business actions require adapter-specific authorization and transaction
controls. [Architecture](https://fastfence.dev/architecture/) · [Policies](https://fastfence.dev/policies/) ·
[Settings](https://fastfence.dev/settings/) · [Evaluation](https://fastfence.dev/testing/).

Licensed under [Apache 2.0](https://github.com/llama-lovers/HackYeah2026-challenge-second/blob/main/LICENSE); see [NOTICE](https://github.com/llama-lovers/HackYeah2026-challenge-second/blob/main/NOTICE). Dependencies retain their
own licenses. Documentation uses MkDocs Material and GitHub Pages at **fastfence.dev**.
