fairsense-agentix 0.1.0__tar.gz

fairsense_agentix-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Lint & Test
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Vscode
+.vscode
+
+# macos
+*.DS_Store
+
+# Claude Files
+CLAUDE.md
+*.faiss
+*.index
+*.json
+*.csv
+# BUT: Allow package data files
+!fairsense_agentix/data/**/*.faiss
+!fairsense_agentix/data/**/*.pkl
+!fairsense_agentix/data/**/*.json
+# Allow UI package manifest and lockfile (reproducible npm install)
+!ui/package.json
+!ui/package-lock.json
+data/indexes/*.json
+data/indexes/README.md
+.env
+.cache/langchain.db
+run_demo.sh
+test_demo.py
+demo_simple.py
+*/node_modules
+/UI_images
+*.js
+*.map

fairsense_agentix-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vector Institute
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fairsense_agentix-0.1.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: fairsense-agentix
+Version: 0.1.0
+Summary: An agentic fairness and AI-risk analysis platform for detecting bias in text and images
+Project-URL: Homepage, https://github.com/VectorInstitute/fairsense-AgentiX
+Project-URL: Documentation, https://vectorinstitute.github.io/fairsense-AgentiX/
+Project-URL: Repository, https://github.com/VectorInstitute/fairsense-AgentiX
+Project-URL: Issues, https://github.com/VectorInstitute/fairsense-AgentiX/issues
+Author-email: Vector AI Engineering <ai_engineering@vectorinstitute.ai>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: accelerate>=0.20.0
+Requires-Dist: faiss-cpu>=1.7.4
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: langchain-anthropic>=0.2.0
+Requires-Dist: langchain-community>=0.3.0
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: langchain-huggingface>=0.1.0
+Requires-Dist: langchain-openai>=0.2.0
+Requires-Dist: langchain>=0.3.0
+Requires-Dist: langgraph>=0.2.56
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: paddleocr>=2.7.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pydantic-settings>=2.7.1
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: pytesseract>=0.3.10
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: requests>=2.31.0
+Requires-Dist: sentence-transformers>=3.0.0
+Requires-Dist: tiktoken<0.12.0,>=0.7.0
+Requires-Dist: torch<2.6.0,>=2.0.0
+Requires-Dist: transformers>=4.35.0
+Requires-Dist: uvicorn>=0.30.0
+Requires-Dist: websockets>=15.0.1
+Description-Content-Type: text/markdown
+
+# FairSense-AgentiX
+
+**An agentic fairness and AI-risk analysis platform developed by the [Vector Institute](https://vectorinstitute.ai/).**
+
+[![code checks](https://github.com/VectorInstitute/fairsense-AgentiX/actions/workflows/code_checks.yml/badge.svg)](https://github.com/VectorInstitute/fairsense-AgentiX/actions/workflows/code_checks.yml)
+[![integration tests](https://github.com/VectorInstitute/fairsense-AgentiX/actions/workflows/integration_tests.yml/badge.svg)](https://github.com/VectorInstitute/fairsense-AgentiX/actions/workflows/integration_tests.yml)
+[![docs](https://github.com/VectorInstitute/fairsense-AgentiX/actions/workflows/docs.yml/badge.svg)](https://github.com/VectorInstitute/fairsense-AgentiX/actions/workflows/docs.yml)
+[![codecov](https://codecov.io/github/VectorInstitute/fairsense-AgentiX/graph/badge.svg?token=83MYFZ3UPA)](https://codecov.io/github/VectorInstitute/fairsense-AgentiX)
+![GitHub License](https://img.shields.io/github/license/VectorInstitute/fairsense-AgentiX)
+
+---
+
+FairSense-AgentiX is an intelligent bias detection and risk assessment platform that uses **agentic AI workflows** to analyze text, images, and datasets for fairness concerns. Unlike traditional ML classifiers, FairSense employs a reasoning agent that plans, selects tools, critiques outputs, and refines them iteratively.
+
+## ✨ Key Features
+
+- 🤖 **Agentic Reasoning** - ReAct loop with dynamic tool selection and self-critique
+- 🔍 **Multi-Modal Analysis** - Text bias detection, image bias detection, and AI risk assessment
+- 🛠️ **Flexible Tool Ecosystem** - OCR, Vision-Language Models, embeddings, FAISS, and LLMs
+- 🌐 **Production-Ready APIs** - FastAPI REST API + WebSocket streaming + React UI
+- ⚙️ **Highly Configurable** - Swap LLM providers, tools, and models on the fly
+
+## 📦 Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install fairsense-agentix
+```
+
+### From Source
+
+```bash
+git clone https://github.com/VectorInstitute/fairsense-AgentiX.git
+cd fairsense-AgentiX
+uv sync
+source .venv/bin/activate
+```
+
+### Requirements
+
+- **Python 3.12+**
+- **4GB+ RAM** (for ML models)
+- **API key** for OpenAI or Anthropic (for LLM functionality)
+
+## 🚀 Quick Start
+
+```python
+from fairsense_agentix import FairSense
+
+# Initialize the engine
+engine = FairSense()
+
+# Analyze text for bias
+result = engine.analyze_text(
+    "We're looking for a young, energetic developer to join our startup team."
+)
+
+print(f"Bias detected: {result.bias_detected}")
+print(f"Risk level: {result.risk_level}")
+for instance in result.bias_instances:
+    print(f"  - {instance['type']} ({instance['severity']}): {instance['text_span']}")
+```
+
+**Full Documentation:** [https://vectorinstitute.github.io/fairsense-AgentiX/](https://vectorinstitute.github.io/fairsense-AgentiX/)
+
+---
+
+## 🧑🏿‍💻 Developing
+
+### Installing dependencies
+
+The development environment can be set up using
+[uv](https://github.com/astral-sh/uv?tab=readme-ov-file#installation). Hence, make sure it is
+installed and then run:
+
+```bash
+uv sync
+source .venv/bin/activate
+```
+
+In order to install dependencies for testing (codestyle, unit tests, integration tests),
+run:
+
+```bash
+uv sync --dev
+source .venv/bin/activate
+```
+
+In order to exclude installation of packages from a specific group (e.g. docs),
+run:
+
+```bash
+uv sync --no-group docs
+```
+## Getting Started
+
+### Run the FastAPI service
+
+```bash
+uv run uvicorn fairsense_agentix.service_api.server:app --reload
+```
+
+Endpoints (all under `/v1/...`):
+
+| Route | Description |
+| --- | --- |
+| `POST /analyze` | JSON payload with `content`, optional `input_type`, `options` |
+| `POST /analyze/upload` | `multipart/form-data` for images |
+| `POST /batch` & `GET /batch/{id}` | Submit + inspect batch jobs |
+| `GET /health` | Health probe |
+| `WS /stream/{run_id}` | Stream telemetry/agent events for a run |
+
+The API auto-detects text/image/CSV inputs, but you can override by setting `input_type` to `bias_text`, `bias_image`, or `risk`.
+
+### Run the Claude-inspired UI
+
+```bash
+cd ui
+npm install
+npm run dev
+```
+
+Set `VITE_API_BASE` (defaults to `http://localhost:8000`) to point at the API. The UI provides:
+
+- Unified input surface (text field + drag/drop image upload)
+- Live agent timeline sourced from telemetry events
+- Downloadable HTML highlights and risk tables
+- Launchpad for batch jobs
+
+### Key configuration knobs
+
+Configure via environment variables (see `.env` for the full list). Most relevant:
+
+| Variable | Description |
+| --- | --- |
+| `FAIRSENSE_LLM_PROVIDER` | `openai`, `anthropic`, or `fake` |
+| `FAIRSENSE_LLM_MODEL_NAME` | e.g. `gpt-4`, `claude-3-5-sonnet` |
+| `FAIRSENSE_LLM_API_KEY` | Provider API key |
+| `FAIRSENSE_OCR_TOOL` | `auto`, `tesseract`, `paddleocr`, `fake` |
+| `FAIRSENSE_CAPTION_MODEL` | `auto`, `blip2`, `blip`, `fake` |
+| `FAIRSENSE_ENABLE_REFINEMENT` | enables evaluator-driven retries (default `true`) |
+| `FAIRSENSE_EVALUATOR_ENABLED` | toggles Phase 7 evaluators |
+| `FAIRSENSE_BIAS_EVALUATOR_MIN_SCORE` | passing score (0–100, default 75) |
+
+All settings can be overridden at runtime:
+
+```bash
+FAIRSENSE_LLM_PROVIDER=anthropic \
+FAIRSENSE_LLM_MODEL_NAME=claude-3-5-sonnet-20241022 \
+uv run uvicorn fairsense_agentix.service_api.server:app
+```
+
+### Running tests
+
+```bash
+uv run pytest
+```
+
+During test collection we automatically override any `.env` values that point at
+real providers/devices so the suite always uses the lightweight `fake`
+toolchain. This guarantees deterministic, offline-friendly tests even if you
+have `FAIRSENSE_LLM_PROVIDER=openai` (or Anthropic) configured locally. To opt-in
+to exercising the real stack, export `FAIRSENSE_TEST_USE_REAL=1` before running
+pytest.
+
+## Acknowledgments
+
+Resources used in preparing this research were provided, in part, by the Province of Ontario, the Government of Canada through CIFAR, and companies sponsoring the Vector Institute.
+
+This research was funded by the European Union's Horizon Europe research and innovation programme under the AIXPERT project (Grant Agreement No. 101214389).
+
+## Contributing
+If you are interested in contributing to the library, please see
+[CONTRIBUTING.md](CONTRIBUTING.md). This file contains many details around contributing
+to the code base, including development practices, code checks, tests, and more.

fairsense_agentix-0.1.0/README.md

@@ -0,0 +1,176 @@
+# FairSense-AgentiX
+
+**An agentic fairness and AI-risk analysis platform developed by the [Vector Institute](https://vectorinstitute.ai/).**
+
+[![code checks](https://github.com/VectorInstitute/fairsense-AgentiX/actions/workflows/code_checks.yml/badge.svg)](https://github.com/VectorInstitute/fairsense-AgentiX/actions/workflows/code_checks.yml)
+[![integration tests](https://github.com/VectorInstitute/fairsense-AgentiX/actions/workflows/integration_tests.yml/badge.svg)](https://github.com/VectorInstitute/fairsense-AgentiX/actions/workflows/integration_tests.yml)
+[![docs](https://github.com/VectorInstitute/fairsense-AgentiX/actions/workflows/docs.yml/badge.svg)](https://github.com/VectorInstitute/fairsense-AgentiX/actions/workflows/docs.yml)
+[![codecov](https://codecov.io/github/VectorInstitute/fairsense-AgentiX/graph/badge.svg?token=83MYFZ3UPA)](https://codecov.io/github/VectorInstitute/fairsense-AgentiX)
+![GitHub License](https://img.shields.io/github/license/VectorInstitute/fairsense-AgentiX)
+
+---
+
+FairSense-AgentiX is an intelligent bias detection and risk assessment platform that uses **agentic AI workflows** to analyze text, images, and datasets for fairness concerns. Unlike traditional ML classifiers, FairSense employs a reasoning agent that plans, selects tools, critiques outputs, and refines them iteratively.
+
+## ✨ Key Features
+
+- 🤖 **Agentic Reasoning** - ReAct loop with dynamic tool selection and self-critique
+- 🔍 **Multi-Modal Analysis** - Text bias detection, image bias detection, and AI risk assessment
+- 🛠️ **Flexible Tool Ecosystem** - OCR, Vision-Language Models, embeddings, FAISS, and LLMs
+- 🌐 **Production-Ready APIs** - FastAPI REST API + WebSocket streaming + React UI
+- ⚙️ **Highly Configurable** - Swap LLM providers, tools, and models on the fly
+
+## 📦 Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install fairsense-agentix
+```
+
+### From Source
+
+```bash
+git clone https://github.com/VectorInstitute/fairsense-AgentiX.git
+cd fairsense-AgentiX
+uv sync
+source .venv/bin/activate
+```
+
+### Requirements
+
+- **Python 3.12+**
+- **4GB+ RAM** (for ML models)
+- **API key** for OpenAI or Anthropic (for LLM functionality)
+
+## 🚀 Quick Start
+
+```python
+from fairsense_agentix import FairSense
+
+# Initialize the engine
+engine = FairSense()
+
+# Analyze text for bias
+result = engine.analyze_text(
+    "We're looking for a young, energetic developer to join our startup team."
+)
+
+print(f"Bias detected: {result.bias_detected}")
+print(f"Risk level: {result.risk_level}")
+for instance in result.bias_instances:
+    print(f"  - {instance['type']} ({instance['severity']}): {instance['text_span']}")
+```
+
+**Full Documentation:** [https://vectorinstitute.github.io/fairsense-AgentiX/](https://vectorinstitute.github.io/fairsense-AgentiX/)
+
+---
+
+## 🧑🏿‍💻 Developing
+
+### Installing dependencies
+
+The development environment can be set up using
+[uv](https://github.com/astral-sh/uv?tab=readme-ov-file#installation). Hence, make sure it is
+installed and then run:
+
+```bash
+uv sync
+source .venv/bin/activate
+```
+
+In order to install dependencies for testing (codestyle, unit tests, integration tests),
+run:
+
+```bash
+uv sync --dev
+source .venv/bin/activate
+```
+
+In order to exclude installation of packages from a specific group (e.g. docs),
+run:
+
+```bash
+uv sync --no-group docs
+```
+## Getting Started
+
+### Run the FastAPI service
+
+```bash
+uv run uvicorn fairsense_agentix.service_api.server:app --reload
+```
+
+Endpoints (all under `/v1/...`):
+
+| Route | Description |
+| --- | --- |
+| `POST /analyze` | JSON payload with `content`, optional `input_type`, `options` |
+| `POST /analyze/upload` | `multipart/form-data` for images |
+| `POST /batch` & `GET /batch/{id}` | Submit + inspect batch jobs |
+| `GET /health` | Health probe |
+| `WS /stream/{run_id}` | Stream telemetry/agent events for a run |
+
+The API auto-detects text/image/CSV inputs, but you can override by setting `input_type` to `bias_text`, `bias_image`, or `risk`.
+
+### Run the Claude-inspired UI
+
+```bash
+cd ui
+npm install
+npm run dev
+```
+
+Set `VITE_API_BASE` (defaults to `http://localhost:8000`) to point at the API. The UI provides:
+
+- Unified input surface (text field + drag/drop image upload)
+- Live agent timeline sourced from telemetry events
+- Downloadable HTML highlights and risk tables
+- Launchpad for batch jobs
+
+### Key configuration knobs
+
+Configure via environment variables (see `.env` for the full list). Most relevant:
+
+| Variable | Description |
+| --- | --- |
+| `FAIRSENSE_LLM_PROVIDER` | `openai`, `anthropic`, or `fake` |
+| `FAIRSENSE_LLM_MODEL_NAME` | e.g. `gpt-4`, `claude-3-5-sonnet` |
+| `FAIRSENSE_LLM_API_KEY` | Provider API key |
+| `FAIRSENSE_OCR_TOOL` | `auto`, `tesseract`, `paddleocr`, `fake` |
+| `FAIRSENSE_CAPTION_MODEL` | `auto`, `blip2`, `blip`, `fake` |
+| `FAIRSENSE_ENABLE_REFINEMENT` | enables evaluator-driven retries (default `true`) |
+| `FAIRSENSE_EVALUATOR_ENABLED` | toggles Phase 7 evaluators |
+| `FAIRSENSE_BIAS_EVALUATOR_MIN_SCORE` | passing score (0–100, default 75) |
+
+All settings can be overridden at runtime:
+
+```bash
+FAIRSENSE_LLM_PROVIDER=anthropic \
+FAIRSENSE_LLM_MODEL_NAME=claude-3-5-sonnet-20241022 \
+uv run uvicorn fairsense_agentix.service_api.server:app
+```
+
+### Running tests
+
+```bash
+uv run pytest
+```
+
+During test collection we automatically override any `.env` values that point at
+real providers/devices so the suite always uses the lightweight `fake`
+toolchain. This guarantees deterministic, offline-friendly tests even if you
+have `FAIRSENSE_LLM_PROVIDER=openai` (or Anthropic) configured locally. To opt-in
+to exercising the real stack, export `FAIRSENSE_TEST_USE_REAL=1` before running
+pytest.
+
+## Acknowledgments
+
+Resources used in preparing this research were provided, in part, by the Province of Ontario, the Government of Canada through CIFAR, and companies sponsoring the Vector Institute.
+
+This research was funded by the European Union's Horizon Europe research and innovation programme under the AIXPERT project (Grant Agreement No. 101214389).
+
+## Contributing
+If you are interested in contributing to the library, please see
+[CONTRIBUTING.md](CONTRIBUTING.md). This file contains many details around contributing
+to the code base, including development practices, code checks, tests, and more.

fairsense_agentix-0.1.0/fairsense_agentix/__init__.py

@@ -0,0 +1,73 @@
+"""FairSense-AgentiX: Agentic Multimodal Bias & AI-Risk Platform.
+
+Quick Start
+-----------
+    >>> from fairsense_agentix import FairSense
+    >>> fs = FairSense()
+    >>> result = fs.analyze_text("Job posting text")
+    >>> print(result.bias_detected, result.risk_level)
+
+Advanced (full control):
+
+    >>> from fairsense_agentix import create_orchestrator_graph
+    >>> graph = create_orchestrator_graph()
+    >>> result = graph.invoke({"input_type": "text", "content": "...", "options": {}})
+"""
+
+# High-level API (recommended)
+# Server launcher (for programmatic usage)
+from fairsense_agentix import server
+from fairsense_agentix.api import (
+    BiasResult,
+    FairSense,
+    ResultMetadata,
+    RiskResult,
+)
+
+# Configuration
+from fairsense_agentix.configs.settings import Settings
+
+# Advanced API (for power users)
+from fairsense_agentix.graphs.orchestrator_graph import create_orchestrator_graph
+
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main API
+    "FairSense",
+    # Result models
+    "BiasResult",
+    "RiskResult",
+    "ResultMetadata",
+    # Configuration
+    "Settings",
+    # Advanced
+    "create_orchestrator_graph",
+    # Server launcher
+    "server",
+]
+
+# ==============================================================================
+# Eager Loading: Preload models at import time for fast first use
+# ==============================================================================
+# This loads all models (LLM, OCR, embeddings, FAISS) when the module is
+# imported, making all subsequent function calls instant (~0.03s instead of ~30s).
+#
+# Trade-off: Import takes 30-60s, but every FairSense().analyze_*() call is instant.
+# Perfect for: Production servers, demos, notebooks (import once, use many times)
+#
+# To disable: Set FAIRSENSE_DISABLE_EAGER_LOADING=true in environment
+import os as _os
+
+
+if _os.getenv("FAIRSENSE_DISABLE_EAGER_LOADING", "").lower() not in (
+    "true",
+    "1",
+    "yes",
+):
+    from fairsense_agentix.tools.registry import get_tool_registry as _get_registry
+
+    # Force singleton creation (preloads all models)
+    _ = _get_registry()
+    del _get_registry  # Clean up namespace