TrueEye is an AI‑powered tool designed to analyze news articles and web content to detect narrative bias, identify the target audience and reveal hidden intentions or manipulative rhetorical structures. In other words, it doesn't just detect fake news — it analyzes who the content is written for and why.
This repository provides a production‑grade Python package containing both
the REST API and a simple frontend. The code is structured under
src/trueeye with proper type hints, tests, continuous integration and
development tooling. A local analysis stub is provided for offline testing.
The previous Hugging Face Space demo is no longer maintained. You can run your own instance locally using the instructions below.
TrueEye offers two usage modes depending on your needs:
- ✅ Modern web interface with custom UI
- ✅ Robust REST API with FastAPI
- ✅ Reproducible environment with Nix/NixOS
- ✅ Automatic setup with a single command
- ✅ Integrated tests and complete documentation
- ✅ Offline mode for development without external APIs
👉 Quick start: ./start.sh (See complete instructions below)
- ✅ 5-minute setup by importing
TrueEyeBeta.json - ✅ No complex configurations - just import and use
- ✅ Visual playground integrated in LangFlow
- ✅ Easy to modify prompts and logic from the UI
- ✅ Cross-platform - works on any OS
👉 See: README_FLOW.md for flow instructions
When given a news article URL, TrueEye performs three consecutive analyses:
- Bias & Narrative Tone — Detects narrative polarity (positive, negative, neutral), identifies rhetorical strategies (fear, polarization, irony) and summarizes the content while flagging questionable claims.
- Audience Profiling — Infers demographic and emotional profile of the target reader and identifies values, beliefs or cognitive biases being exploited.
- Intent & Risk Evaluation — Detects manipulative discourse or hidden agendas and highlights information gaps and potential societal risk.
The report includes links to trustworthy sources for fact‑checking.
The project consists of two main components:
- 🧠 Backend — A REST API built with FastAPI and packaged as a
Python library. The API is created via
trueeye.create_app()and can be run usinguvicorn. - 🧱 Frontend — A minimal static web interface built with TailwindCSS (served from the package's static directory). It allows users to input a URL, trigger analysis and view the result.
The heavy lifting is performed by a remote LangFlow pipeline via the
FLOW_API_URL environment variable. For offline testing you can set
TE_PROVIDER=local and the API will return a stubbed response.
TrueEye_v1/
├── src/trueeye/
│ ├── __init__.py # Exposes create_app()
│ ├── api.py # FastAPI application factory and endpoints
│ ├── models.py # Pydantic models
│ ├── utils.py # Helper functions
│ └── static/
│ └── index.html # Frontend UI
├── tests/ # Test suite
├── pyproject.toml # Project metadata and dependencies
├── .pre-commit-config.yaml
├── .github/workflows/ci.yml
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── LICENSE.txt # Non‑commercial license
└── README.md # Project documentation (this file)
# Option 1: Using start.sh script (recommended)
./start.sh
# Option 2: Using Makefile
make start
# Option 3: Direct Nix command
nix-shell --run "trueeye-dev"The project includes automatic configuration. On first use:
- An
.envfile will be automatically created from.env.example - The Python environment will be configured with all dependencies
- The application will start in local mode (no external connection)
# To edit configuration:
./start.sh config
# or
make config
# For manual configuration:
cp .env.example .env
# Then edit .env with your favorite editorMain variables:
TE_PROVIDER=local→ Test mode (no external API)TE_PROVIDER=remote→ Production mode (requiresFLOW_API_URL)PORT=8000→ Server portHOST=0.0.0.0→ Server host
# Commands with start.sh:
./start.sh start # Start application (default)
./start.sh test # Run tests
./start.sh config # Edit configuration
./start.sh shell # Open development shell
./start.sh help # Show help
# Commands with Makefile:
make start # Start application
make test # Run tests
make config # Edit configuration
make shell # Open development shell
make clean # Clean temporary files
make check # Verify configuration
make help # Show helpThe project includes a fully configured shell.nix that provides:
- ✅ Python 3.10+ with all dependencies
- ✅ FastAPI and Uvicorn pre-configured
- ✅ Testing tools (pytest, httpx)
- ✅ Development utilities (mypy, curl, jq)
- ✅ Custom scripts to make usage easy
- ✅ Automatic loading of environment variables
- ✅ Automatic PYTHONPATH configuration
- Automatic configuration: Creates
.envif it doesn't exist - Environment validation: Verifies configuration at startup
- Multiple interfaces: Bash script, Makefile, Nix commands
- Development mode: Auto-reload with
--reload - Integrated testing: Test suite ready to use
- Automatic cleanup: Temporary file management
# 1. Clone/access the project
cd /path/to/trueeye_v1
# 2. Run (everything gets configured automatically)
./start.sh
# 3. Access the application
firefox http://localhost:8000To verify that everything is properly configured:
# Verify dependencies and configuration
make check
# View environment information
make dev-info
# Run tests to validate functionality
./start.sh test- FastAPI — High-performance Python web framework
- Uvicorn — ASGI server with asyncio support
- Pydantic — Data validation with type hints
- Requests — HTTP client for API integration
- HTML5/JavaScript — Minimal and functional frontend
- TailwindCSS — Utility-first CSS framework
- Marked.js — Markdown processing for responses
- Nix/NixOS — Reproducible environment management
- pytest — Testing framework
- mypy — Static type checking
- Shell Scripts — Task automation
- LangFlow API — AI analysis pipeline (remote mode)
- Local mode — Stub responses for offline development
Gonzalo Romero (DeepRat)
AI, Software & Systems Engineer · Prompt Engineer · Full‑Stack Developer
🔗 Web | Hugging Face | GitHub | LinkedIn | Medium