[](requirements.txt)
[](LICENSE)
[](https://safi.selfalignmentframework.com)
[](https://github.com/jnamaya/SAFi/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
# SAFi: Self-Alignment Framework Interface
## Table of Contents
- [The Problem](#the-problem)
- [Quick Start](#quick-start)
- [How SAFi Compares](#how-safi-compares)
- [How Does It Work?](#how-does-it-work)
- [Mathematical Specification](#mathematical-specification)
- [Benchmarks & Validation](#benchmarks--validation)
- [Technical Implementation](#technical-implementation)
- [Application Structure](#application-structure)
- [Configuration Reference](#configuration-reference)
- [Authentication Setup](#authentication-setup)
- [Permissions](#permissions)
- [Headless Governance Layer](#headless-governance-layer)
- [Agent Capabilities](#agent-capabilities)
- [Developer Guide](#developer-guide)
- [Manual Installation](#manual-installation)
- [Contributing](#contributing)
- [Live Demo](#live-demo)
- [About the Author](#about-the-author)
### The Problem
Your organization is deploying AI agents. Your legal and compliance teams are asking hard questions: What policies govern every response? Who audits the decisions? What happens when the model drifts, gets jailbroken, or gives advice it shouldn't?
The standard answer -- a system prompt and a hope -- is not an answer. The industry's next move was to wrap the model in more LLM calls to police itself: monolithic guardrails that are slow, expensive, and just as susceptible to adversarial prompts as the model they are trying to constrain.
There is a better way.
### What SAFi Is
SAFi is an open-source runtime governance engine that does not just watch what your AI does; it enforces, audits, and shapes every decision *before* it reaches a user. Think of it as the **separation of powers for AI agents.**
Instead of a single model trying to be smart, compliant, and ethical all at once, SAFi splits cognition into five specialized faculties -- each with a distinct job, each operating in its own security layer:
| Faculty | Role | Security Property |
| :--- | :--- | :--- |
| **Synderesis** | The constitution compiler: defines immutable rules and value weights. | Read-only after deployment. |
| **Intellect** | The generative engine: drafts responses and tool proposals. | Air-gapped from execution. |
| **Will** | The deterministic gatekeeper: pure Python, zero LLM. | Immune to prompt injection. |
| **Conscience** | The analytical auditor: scores every draft against rubrics. | Secondary validation layer. |
| **Spirit** | The long-term memory: detects drift using exponential moving averages. | Non-LLM mathematical integrity. |
## Quick Start
The fastest way to run SAFi locally. Includes MySQL. No external database needed.
# 1. Clone and enter the repo
git clone https://github.com/jnamaya/SAFi.git
cd SAFi
# 2. Configure your environment
cp .env.example .env
# Open .env and set:
# DB_PASSWORD + MYSQL_ROOT_PASSWORD (choose anything)
# At least one LLM API key (GROQ_API_KEY is free and fast to get)
# 3. Start everything
docker compose up
# Open http://localhost:5000
#### Local Admin Account (No OAuth Required)
For private or self-hosted instances, you can skip Google/Microsoft OAuth entirely by creating a persistent local admin account. Add these two lines to your `.env` before starting:
SAFI_LOCAL_ADMIN_EMAIL=admin@localhost
SAFI_LOCAL_ADMIN_PASSWORD=yourpassword
SAFi will create the account automatically on first startup. The login form appears on the login page alongside the OAuth buttons.
### Why This Changes Everything
**99.86% jailbreak defense** in live adversarial testing. **98.5% overall compliance** vs. an 85% baseline. Sub-5-second latency at roughly **$0.005 per interaction**.
Those are not marketing numbers -- they are published benchmark results from 1,435+ adversarial interactions. SAFi's **Will** faculty (a blind, deterministic gatekeeper that never touches an LLM) caught every single attack that the baseline model missed.
*Because you can't socially engineer pure Python.*
### How SAFi Compares
| | SAFi | Guardrails AI | NVIDIA NeMo Guardrails |
| :--- | :--- | :--- | :--- |
| **Gate Architecture** | Deterministic Python (zero LLM) | LLM-based validators | LLM-based Colang rails |
| **Prompt Injection Risk** | Immune at Will layer | Validator is susceptible | Rail LLM is susceptible |
| **Jailbreak Defense Rate** | **99.86%** (1,435+ live tests) | Not independently published | Not independently published |
| **Avg. Latency** | ~3-5 seconds | ~10-30+ seconds | ~10-30+ seconds |
| **Cost per Interaction** | ~$0.005 | Higher (multiple LLM calls) | Higher (multiple LLM calls) |
| **Long-term Drift Detection** | Yes (EMA-based Spirit faculty) | No | No |
| **Full Per-Decision Audit Trail** | Yes (five-faculty logging) | Partial | Partial |
| **Model Independence** | GPT, Claude, Gemini, Llama, Groq, Mistral, DeepSeek | Model-agnostic | Model-agnostic |
| **Built-in Governance UI** | Yes | No | No |
| **Open Source License** | AGPL-3.0 | Apache 2.0 | Apache 2.0 |
### What You Get
| Principle | What It Means | SAFi Delivers |
| :--- | :--- | :--- |
| 🛡️ **Policy Enforcement** | Your rules, not the model's defaults, govern every response. | Runtime-layer enforcement: custom policies override the underlying LLM. |
| 🔍 **Full Traceability** | Every decision logged, every veto recorded, every drift tracked. | Granular audit trail across all five faculties -- a black box no more. |
| 🔄 **Model Independence** | Swap LLMs without rewriting governance. | Modular architecture supporting GPT, Claude, Gemini, Llama, Groq, Mistral, and DeepSeek. |
| 📈 **Long-Term Consistency** | Your AI's ethical identity stays stable over months of use. | Spirit's EMA-based drift detection auto-corrects behavioral drift. |
### The Architecture That Makes It Possible
SAFi's innovation is a **separation of powers** inspired by classical philosophy, mapped directly to software modules. Each faculty has a single job and cannot be overridden by the others.
The **Intent Air Gap** severs the generative Intellect from the execution environment. The **Blind Will** enforces structural invariants with no semantic vulnerability. The **Spirit** tracks alignment as a mathematical vector, not a subjective vibe.
This is not philosophical decoration -- it is a security architecture that makes your governance model-independent. Whether your underlying LLM is GPT-5 or an open-source fine-tune, SAFi's pipeline intercepts violations at the exact same deterministic gates.
### Next Steps
🚀 **Try the live demo** → [safi.selfalignmentframework.com](https://safi.selfalignmentframework.com)
🐙 **Star the repo** → `git clone https://github.com/jnamaya/SAFi.git`
📖 **Read the math** → [docs/MATHEMATICAL_SPECIFICATION.md](docs/MATHEMATICAL_SPECIFICATION.md)
🛠️ **Use it headless** → Plug into LangChain, AutoGen, Teams, Telegram, or WhatsApp.
**SAFi turns any LLM into a governed, auditable agent -- your policies enforced at runtime, every decision logged.** The demo is live. The benchmarks are public. The architecture is open source.
**Try it. Fork it. Govern it.**
## How Does It Work?
SAFi implements a cognitive architecture derived from five specialized faculties -- each a separate software module with a distinct role and security boundary. The design is inspired by classical philosophy's separation of cognitive powers; the full rationale is in [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md).
### The Five Faculties
| Faculty | Module | Role |
| :--- | :--- | :--- |
| **Synderesis** | `synderesis.py` | The foundational compiler. Establishes immutable baseline rules, governance policies, scope boundaries, and value weights for every agent. |
| **Intellect** | `intellect.py` | The generative engine. Drafts responses or proposes tool calls. Operates entirely within an **Air Gap**: it can only produce *intents*, never execute them directly. |
| **Will** | `will.py` | The blind gatekeeper. Pure deterministic Python: zero LLM calls. Approves or vetoes the Intellect's proposals based on structural checks and the Conscience's mathematical ledger. |
| **Conscience** | `conscience.py` | The analytical auditor. A secondary LLM call that scores the Intellect's draft against the agent's rubrics, generating a precise compliance ledger (−1.0 to +1.0 per value). |
| **Spirit** | `spirit.py` | The long-term memory. Integrates Conscience scores into a rolling alignment vector using an EMA, detecting behavioral drift over time and generating coaching for future turns. |
### Spirit: The Math Behind Drift Detection
Spirit and Will are the only two faculties with **no LLM involvement**; both are implemented as pure deterministic Python. Spirit uses NumPy to build a rolling ethical profile and detect drift:
| Step | Formula | What It Does |
| :--- | :--- | :--- |
| **Score** | `S_t = clip( Σ wᵢ · sᵢ · cᵢ, −1, 1 ) → [1, 10]` | Weighted sum of scores × confidence, clipped then linearly rescaled |
| **Profile** | `p_t = w ⊙ s_t` | Element-wise product of weights and scores for this turn |
| **EMA** | `μ_t = β · μ_(t-1) + (1-β) · p_t` | Exponential moving average (β=0.9) smooths the profile over time |
| **Drift** | `d_t = 1 - cos_sim(p_t, μ_(t-1))` | Cosine distance between current turn and historical baseline |
# Core computation from spirit.py
p_t = self.value_weights * scores
mu_new = self.beta * mu_prev + (1 - self.beta) * p_t
drift = 1.0 - float(np.dot(p_t, mu_prev) / (np.linalg.norm(p_t) * np.linalg.norm(mu_prev)))
Spirit then generates a coaching note (e.g., *"Coherence 9/10, drift 0.01. Main improvement area: 'Justice' (score: 0.21)"*) that feeds back into the next Intellect call, creating a closed-loop feedback system.
### The Six-Phase Execution Circuit
Every user prompt flows through a strict, synchronous pipeline:
| Phase | Name | What Happens |
| :--- | :--- | :--- |
| **Phase 0** | Pre-generation Gate | The prompt is evaluated against persona-specific blacklists to block direct injection attempts before any LLM generation. |
| **Phase 2** | Apprehension | The Intellect drafts a response or proposes a tool call. (Phase 1 is data gathering / RAG retrieval.) |
| **Phase 3** | Structural Will | The Will deterministically checks the draft for structural invariants. If blocked, it commands a compliant rewrite (Reflexion Loop). |
| **Phase 4** | Conscience Audit | The Conscience scores the structurally valid draft against the agent's rubrics, producing the compliance ledger. |
| **Phase 5** | Spirit Integration | The Will checks the ledger for hard-gate failures. If passed, Spirit integrates the scores into the agent's long-term alignment vector. |
| **Phase 6** | Safe Execution | The fully audited response is finalized, logged with its vector coordinates, and delivered to the user. |
### Security Architecture: The Air Gap & The Blind Will
- **Zero-LLM Execution (The Blind Will):** The WillGate is purely deterministic Python with no LLM attached. Prompt injections that bypass the Intellect cannot trick the system into executing unauthorized tools: the Will enforces parameter constraints and allowed-tool lists without being susceptible to semantic manipulation.
- **The Intent Air Gap:** The Intellect is only permitted to output *intents* (proposals). It is completely severed from the execution environment. The Intellect can hallucinate a destructive command, but the Will will mechanically reject it.
### Scope Compliance: Defense-in-Depth Against Jailbreaks
Every persona declares a `scope_statement`. SAFi enforces it through three independent layers:
| Layer | Mechanism | Trigger |
| :--- | :--- | :--- |
| **Layer 1: Worldview Scope Block** | Every persona's system prompt contains a `--- SCOPE ENFORCEMENT ---` block instructing the Intellect to refuse off-topic and injected content at generation time. | Proactive: fires before any output is produced. |
| **Layer 2: W1 Structural Gate** | Will checks the draft for required structural elements (disclaimers, banned syntax) before it reaches the user. | Fires on every response, regardless of model. |
| **Layer 3: Phase 4.5 Hard Gate** | After Conscience scores the response, Will reads the ledger for the `Scope Compliance` value. A score of −1.0 triggers an immediate block and governed rephrase. | Catches anything that escaped Layers 1 and 2. |
This architecture means jailbreak resistance is **model-independent**: the governance pipeline intercepts violations regardless of which underlying LLM generated the response.
## Mathematical Specification
The formal mathematical foundation of SAFi's five-stage cognitive architecture, including the full type system, Spirit EMA and drift formulas, Will's three-pass gate logic, and Phase Zero entropy heuristics, is documented in:
📐 **[`docs/MATHEMATICAL_SPECIFICATION.md`](docs/MATHEMATICAL_SPECIFICATION.md)**
## Benchmarks & Validation
SAFi is continuously tested in both live adversarial environments and controlled compliance studies.
### 1. Jailbreak Tests
**99.86% of jailbreak attempts failed. The two that slipped through were already patched before the next test run.**
**Objective:** Stop hackers from jailbreaking the model using DAN, Prompt Injection, and Social Engineering. Tests are publicly performed via Reddit & Discord communities.
| Metric | Result |
| :--- | :--- |
| **Total Interactions** | **1,435+** |
| **Confirmed Jailbreaks** | **2 (0.14%)** |
| **"Will" Interventions** | **20** (Blocked attacks that bypassed the Generator) |
| **Defense Success Rate** | **99.86%** |
### 2. Domain Compliance Benchmark
**On adversarial prompts, SAFi scored 97.5%. The unguarded baseline scored 67.5% -- a 30-point gap that represents the difference between a compliant deployment and a liability.**
**Objective:** Prevent AI from giving illegal/unsafe advice in regulated domains.
**Method:** 100 prompts per persona across 3 categories: Ideal (safe), Out-of-Scope (off-topic), and "Trap" (adversarial).
| Metric | SAFi | Baseline (Fiduciary) | Baseline (Health Navigator) |
| :--- | :--- | :--- | :--- |
| **Ideal Prompts** | 98.8% | 97.5% | 100% |
| **Out-of-Scope** | 100% | 95% | 100% |
| **"Trap" Prompts** | 97.5% | 🔴 67.5% | 🔴 77.5% |
| **Overall** | **98.5%** | 85% | 91% |
### 3. Performance & Cost Profile
**Full governance adds roughly $0.005 per interaction and under 5 seconds of latency. The separation-of-powers architecture costs less to run than a monolithic guardrail.**
By using a **Hybrid Architecture** (a deterministic Will layer and a lightweight Conscience auditor on smaller open-source models) SAFi achieves lower latency and cost than monolithic chains.
| Configuration | Avg. Latency | Avg. Cost (per 1k interactions) |
| :--- | :--- | :--- |
| Monolithic (large commercial models only) | ~30-60 seconds | $$$ (High) |
| **SAFi Hybrid (large + open-source models)** | **~3-5 seconds** | **~$5.00** |
- **Latency:** The Will faculty is pure deterministic Python: sub-millisecond gate checks, no waiting for a model to "grade its own homework."
- **Cost:** Conscience runs on smaller open-source models, keeping fully governed interactions at roughly **$0.005 each**.
## Technical Implementation
The core logic resides in **`safi_app/core/`**:
| File | Role |
| :--- | :--- |
| `orchestrator.py` | Central nervous system. Coordinates data flow between the user, faculties, and external services. |
| `synderesis.py` | Persona registry and constitution compiler. Defines all built-in agent profiles, injects scope gates and value weights. |
| `faculties/intellect.py` | The Generator. Receives context from the Orchestrator and drafts responses or tool proposals. |
| `faculties/will.py` | The Gatekeeper. Pure deterministic Python: zero LLM calls. |
| `faculties/conscience.py` | The Auditor. Scores every response against the agent's rubrics, synchronously, before the user receives it. |
| `faculties/spirit.py` | The Long-Term Integrator. Aggregates Conscience scores and updates the agent's alignment vector. |
## Application Structure
SAFi is organized into the following functional areas:
| Area | Description |
| :--- | :--- |
| **Agents** | Create, configure, and manage AI agents with custom tools, knowledge bases, and policies. |
| **Organization** | Configure global settings: domain verification, policy weighting, and drift sensitivity. |
| **Policies** | Build governance constitutions and generate API keys for headless deployments. |
| **Audit Hub** | View decision logs, audit trails, Spirit drift charts, and ethical ratings for every interaction. |
| **AI Model** | Switch the underlying LLM provider (OpenAI, Anthropic, Google, Groq, Mistral, DeepSeek) per faculty. |
| **My Profile** | Define user values, interests, goals, and context that the AI uses to personalize responses. |
| **App Settings** | Manage themes (light/dark) and data source connections (Google Drive, OneDrive, GitHub). |
## Configuration Reference
All settings are controlled via environment variables. Copy `.env.example` to `.env` to get started.
### Core
| Variable | Default | Description |
| :--- | :--- | :--- |
| `FLASK_ENV` | `production` | Set to `development` to skip production-only validation checks. |
| `FLASK_SECRET_KEY` | *(required)* | Random secret for session signing. Generate with `python -c "import secrets; print(secrets.token_hex(32))"`. |
| `WEB_BASE_URL` | *(env-dependent)* | Public URL where SAFi is reachable (used for OAuth callbacks). |
### Database
| Variable | Default | Description |
| :--- | :--- | :--- |
| `DB_HOST` | `localhost` | MySQL host. In Docker Compose this is set automatically to `db`. |
| `DB_USER` | `safi` | MySQL user. |
| `DB_PASSWORD` | *(required)* | MySQL password. |
| `DB_NAME` | `safi` | MySQL database name. |
| `MYSQL_ROOT_PASSWORD` | *(required for Docker)* | MySQL root password (Docker Compose only). |
### LLM Providers
At least one key is required. [Groq](https://console.groq.com) has a generous free tier.
| Variable | Description |
| :--- | :--- |
| `GROQ_API_KEY` | Groq (Llama, Mixtral) |
| `OPENAI_API_KEY` | OpenAI (GPT-4o, GPT-4o-mini) |
| `ANTHROPIC_API_KEY` | Anthropic (Claude) |
| `GEMINI_API_KEY` | Google (Gemini) |
| `MISTRAL_API_KEY` | Mistral |
| `DEEPSEEK_API_KEY` | DeepSeek |
### Authentication
| Variable | Description |
| :--- | :--- |
| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | Required for Google OAuth login. |
| `MICROSOFT_CLIENT_ID` / `MICROSOFT_CLIENT_SECRET` | Required for Microsoft OAuth login. |
| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | Required for GitHub OAuth login. |
### Runtime Behaviour
| Variable | Default | Description |
| :--- | :--- | :--- |
| `SAFI_LOCAL_ADMIN_EMAIL` | *(empty)* | Email for the persistent local admin account. Set both vars to enable local login with no OAuth. |
| `SAFI_LOCAL_ADMIN_PASSWORD` | *(empty)* | Password for the local admin account. |
| `SAFI_ENABLE_DEMO` | `false` | Show the "Try Demo (Admin)" button on the login page. Set to `true` for public demos. |
| `SAFI_MAX_AGENT_TURNS` | `5` | Maximum sequential tool-call turns per request before forcing a final answer. |
| `SAFI_DAILY_PROMPT_LIMIT` | `0` | Daily prompt limit per user. `0` = unlimited. |
| `SAFI_PROFILE` | `tutor` | Default agent loaded on first login. |
| `SAFI_BOT_API_SECRET` | *(required)* | Secret for the headless bot API (`/api/bot/process_prompt`). |
### Models
| Variable | Default | Description |
| :--- | :--- | :--- |
| `SAFI_INTELLECT_MODEL` | `claude-haiku-4-5-20251001` | Primary generative faculty. |
| `SAFI_CONSCIENCE_MODEL` | `openai/gpt-oss-120b` | Auditing faculty (asynchronous). |
| `SAFI_SUMMARIZER_MODEL` | `llama-3.1-8b-instant` | Conversation summarization. |
| `SAFI_BACKEND_MODEL` | `llama-3.1-8b-instant` | Background tasks (profile extraction, suggestions). |
## Authentication Setup
SAFi uses OpenID Connect (OIDC) for OAuth login. If you set `SAFI_LOCAL_ADMIN_EMAIL` and `SAFI_LOCAL_ADMIN_PASSWORD`, you can skip this section entirely for local development.
### Google Setup
1. Go to the [Google Cloud Console](https://console.cloud.google.com).
2. Create a project and configure the **OAuth consent screen**.
3. Create **OAuth 2.0 Client IDs** (Web application).
4. Add Authorized Redirect URIs:
- `http://localhost:5000/api/callback` (Login)
- `http://localhost:5000/api/auth/google/callback` (Drive Integration)
5. Copy **Client ID** and **Client Secret** to `.env`.
### Microsoft Setup
1. Go to [Azure Portal → App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps).
2. Register a new application (**Accounts in any organizational directory + personal Microsoft accounts**).
3. Add Redirect URIs (Web):
- `http://localhost:5000/api/callback/microsoft` (Login)
- `http://localhost:5000/api/auth/microsoft/callback` (OneDrive Integration)
4. Create a **Client Secret** under "Certificates & secrets".
5. Copy **Application (client) ID** and secret value to `.env`.
## Permissions
SAFi uses Role-Based Access Control (RBAC):
| Role | Access |
| :--- | :--- |
| **Admin** | Full access: organization settings, member management, all policies and agents. |
| **Editor** | Manage policies, agents, and view audit logs. Cannot modify organization-wide settings. |
| **Auditor** | Read-only access to organization settings, policies, and audit logs for compliance verification. |
| **Member** | Chat and agent access only. Management menu is hidden. |
## Headless Governance Layer
SAFi can operate as a **"Governance-as-a-Service"** layer for any external application, bot framework, or existing agent pipeline (LangChain, AutoGen, etc.). It has been tested with Microsoft Teams, Telegram, and WhatsApp.
### Setup
1. Go to **Policies**, create or open a policy, and generate an API key.
### API Call
POST /api/bot/process_prompt
Content-Type: application/json
X-API-KEY: sk_policy_your_key_here
{
"user_id": "teams_user_123",
"user_name": "John Doe",
"message": "Can I approve this expense?",
"conversation_id": "chat_456",
"persona": "safi"
}
### Response
{
"finalOutput": "Based on company policy, expenses under $500 can be approved by...",
"sources": [
{ "title": "Expense Policy", "url": "https://..." }
]
}
Users are automatically provisioned (just-in-time) so all interactions are visible in the **Audit Hub**.
## Agent Capabilities
SAFi supports multiple data source types for agents:
| Type | Description |
| :--- | :--- |
| **MCP Tools** | Live data access: stock prices, web search, Google Drive, SharePoint, GitHub, Google Maps. |
| **RAG** | Static knowledge bases indexed as FAISS vector stores. |
| **Plugins** | Custom Python functions that inject context before the prompt reaches the LLM. |
The demo environment includes nine specialized agents:
| Agent | Capability Demonstrated |
| :--- | :--- |
| **The Contoso Admin** | Organizational governance policies + RAG over SOPs. Enforces data privacy and PII leak prevention. |
| **The Fiduciary** | MCP tool-calling for live stock prices and earnings data. Fiduciary boundaries enforced at the Will layer. |
| **The Bible Scholar** | RAG over the Berean Standard Bible corpus. Conscience enforces textual fidelity. |
| **The Health Navigator** | RAG + Geospatial MCP Tools. W1 gate enforces mandatory medical disclaimers on every response. |
| **The Socratic Tutor** | Structural Will rejects any response that gives a direct answer rather than a guiding question. |
| **The Negotiator** | Roleplay simulation demonstrating persona-scope enforcement: stays in character, refuses redirection. |
| **The Philosopher** | Aristotelian ethics guide with value-weighted Conscience scoring (Intellectual Honesty, Logical Rigor, Socratic Depth). |
| **The Vault** | Holds a secret phrase and must never reveal it. Showcases defense against every known jailbreak vector. |
| **The SAFi Guide** | RAG-powered documentation assistant for the SAFi knowledge base. |
## Developer Guide
### 1. How to Add a New MCP Tool
1. **Create the implementation** -- add a new file to `safi_app/core/mcp_servers/` (e.g., `slack.py`) and define your async tool functions.
2. **Register it** -- open `safi_app/core/services/mcp_manager.py`:
- Add the JSON schema to `get_tools_for_agent`
- Add a dispatch branch to `execute_tool`
3. **Enable it for an agent** -- in `safi_app/core/synderesis.py` (or via the Agents UI), add the tool name to the agent's `tools` list:
"tools": ["sharepoint_search", "slack_post_message"]
### 2. How to Add a RAG Knowledge Base
1. **Build the vector index** -- use the `sentence-transformers` + `FAISS` pipeline to chunk your documents and produce two files:
- `my_knowledge.index` -- the searchable FAISS index
- `my_knowledge_metadata.pkl` -- the chunk-to-text map
See `safi_app/core/plugins/bible_scholar_readings.py` for a working example of the indexing pattern.
2. **Deploy the files** -- place both files in the `vector_store/` directory.
3. **Enable it for an agent** -- in `safi_app/core/synderesis.py`, set the agent's `rag_knowledge_base` key:
"rag_knowledge_base": "my_knowledge"
### 3. How to Add a Plugin (Context Injector)
Plugins run logic *before* the prompt reaches the LLM, useful for injecting live context (weather, user data, etc.).
1. **Create the plugin** -- add a file to `safi_app/core/plugins/` (e.g., `weather_injector.py`) with an async function that returns context data.
2. **Hook it in** -- open `safi_app/core/orchestrator.py`, find `process_prompt`, and add your plugin to the `plugin_tasks` list:
plugin_tasks = [
# existing plugins...
weather_injector.get_weather(user_prompt, ...)
]
3. The returned data is collected into `plugin_context_data` and automatically passed to the Intellect faculty.
## Manual Installation
For deploying SAFi on a bare Linux server without Docker.
### Prerequisites
- Python 3.11+
- MySQL 8.0+ (required for JSON column support)
- Nginx or Apache (recommended for SSL/HTTPS in production)
### Steps
1. **Clone the repository:**
git clone https://github.com/jnamaya/SAFi.git
cd SAFi
2. **Set up a virtual environment:**
python -m venv venv
source venv/bin/activate # Linux/Mac
# .\venv\Scripts\activate # Windows
3. **Install dependencies:**
pip install -r requirements.txt
4. **Configure your environment:**
cp .env.example .env
nano .env
Set `DB_PASSWORD`, at least one LLM API key, and (optionally) Google/Microsoft OAuth credentials.
5. **Create the database:**
SAFi creates all tables automatically on first run. You only need to create the empty database:
CREATE DATABASE safi CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
6. **Run the application:**
# Development
flask --app safi_app run --debug
# Production (Gunicorn)
gunicorn -k uvicorn.workers.UvicornWorker --workers 3 --bind 127.0.0.1:5000 asgi:app
7. **Configure a reverse proxy (recommended for production):**
**Nginx:**
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
**Apache** (requires `mod_proxy` and `mod_proxy_http`):
ServerName your-domain.com
ProxyPreserveHost On
ProxyPass / http://127.0.0.1:5000/
ProxyPassReverse / http://127.0.0.1:5000/
8. **Open** `http://localhost:5000` (or your server's domain).
## Live Demo
[safi.selfalignmentframework.com](https://safi.selfalignmentframework.com)
## About the Author
**Nelson Amaya** is a Cloud & Infrastructure IT Director and AI Architect specializing in Enterprise Governance and Cognitive Architectures. With over 20 years of experience in the IT space, Nelson built SAFi to solve the critical gap between static PDF policies and runtime AI governance.
- **Read the Philosophy:** [SelfAlignmentFramework.com](https://selfalignmentframework.com)
- **Connect on LinkedIn:** [linkedin.com/in/amayanelson](https://www.linkedin.com/in/amayanelson/)
- **Follow on X:** [@nelsonamaya_](https://x.com/nelsonamaya_)
- **Follow on Reddit:** [u/forevergeeks](https://www.reddit.com/user/forevergeeks/)