{"id":30894010,"url":"https://github.com/deepratai/trueeye","last_synced_at":"2026-05-01T21:35:25.765Z","repository":{"id":310914355,"uuid":"1041735692","full_name":"DeepRatAI/TrueEye","owner":"DeepRatAI","description":"Media Literacy System powered by AI - Analyze news for bias and manipulation.","archived":false,"fork":false,"pushed_at":"2025-08-28T18:43:36.000Z","size":2363,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-29T00:54:31.939Z","etag":null,"topics":["ai-ethics","bias-detection","claude","claude-ai","constitutional-ai","content-analysis","fact-checking","fastapi","langflow","misinformation","misinformation-detection","news-analysis","nixos","python"],"latest_commit_sha":null,"homepage":"https://deepratai.github.io/TrueEye/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DeepRatAI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-21T00:01:34.000Z","updated_at":"2025-08-28T18:53:29.000Z","dependencies_parsed_at":"2025-08-21T02:26:35.614Z","dependency_job_id":"df28ac50-b39c-4f54-97c1-9a3848220909","html_url":"https://github.com/DeepRatAI/TrueEye","commit_stats":null,"previous_names":["deepratai/trueeye"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DeepRatAI/TrueEye","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepRatAI%2FTrueEye","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepRatAI%2FTrueEye/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepRatAI%2FTrueEye/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepRatAI%2FTrueEye/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DeepRatAI","download_url":"https://codeload.github.com/DeepRatAI/TrueEye/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepRatAI%2FTrueEye/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274231571,"owners_count":25245624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-ethics","bias-detection","claude","claude-ai","constitutional-ai","content-analysis","fact-checking","fastapi","langflow","misinformation","misinformation-detection","news-analysis","nixos","python"],"created_at":"2025-09-08T21:02:05.090Z","updated_at":"2026-05-01T21:35:25.731Z","avatar_url":"https://github.com/DeepRatAI.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![TrueEye Banner](banner.gif)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.68+-green.svg)](https://fastapi.tiangolo.com)\n[![LangFlow Ready](https://img.shields.io/badge/LangFlow-Ready-purple.svg)](https://github.com/logspace-ai/langflow)\n[![NixOS](https://img.shields.io/badge/NixOS-Reproducible-blue.svg)](https://nixos.org/)\n\n# 🧿 TrueEye — Intelligent Media Literacy System\n\n**TrueEye** is an AI‑powered tool designed to analyze news articles and web\ncontent to detect narrative bias, identify the target audience and reveal\nhidden intentions or manipulative rhetorical structures. In other words, it\ndoesn't just detect fake news — it analyzes **who** the content is written\nfor and **why**.\n\nThis repository provides a production‑grade Python package containing both\nthe REST API and a simple frontend. The code is structured under\n`src/trueeye` with proper type hints, tests, continuous integration and\ndevelopment tooling. A local analysis stub is provided for offline testing.\n\n## 🚀 Demo\n\nThe previous Hugging Face Space demo is no longer maintained. You can run\nyour own instance locally using the instructions below.\n\n## 🚀 Usage Options\n\nTrueEye offers **two usage modes** depending on your needs:\n\n### 🏗️ **Option A: Complete Application (Recommended for production)**\n\n- ✅ **Modern web interface** with custom UI\n- ✅ **Robust REST API** with FastAPI\n- ✅ **Reproducible environment** with Nix/NixOS\n- ✅ **Automatic setup** with a single command\n- ✅ **Integrated tests** and complete documentation\n- ✅ **Offline mode** for development without external APIs\n\n👉 **Quick start**: `./start.sh` (See complete instructions below)\n\n### ⚡ **Option B: Direct LangFlow Flow (Quick to try)**\n\n- ✅ **5-minute setup** by importing `TrueEyeBeta.json`\n- ✅ **No complex configurations** - just import and use\n- ✅ **Visual playground** integrated in LangFlow\n- ✅ **Easy to modify** prompts and logic from the UI\n- ✅ **Cross-platform** - works on any OS\n\n👉 **See**: [`README_FLOW.md`](README_FLOW.md) for flow instructions\n\n---\n\n## 🧩 What Does TrueEye Do?\n\nWhen given a news article URL, **TrueEye** performs three consecutive\nanalyses:\n\n1. **Bias \u0026 Narrative Tone** — Detects narrative polarity (positive,\n   negative, neutral), identifies rhetorical strategies (fear, polarization,\n   irony) and summarizes the content while flagging questionable claims.\n2. **Audience Profiling** — Infers demographic and emotional profile of\n   the target reader and identifies values, beliefs or cognitive biases being\n   exploited.\n3. **Intent \u0026 Risk Evaluation** — Detects manipulative discourse or hidden\n   agendas and highlights information gaps and potential societal risk.\n\nThe report includes links to trustworthy sources for fact‑checking.\n\n## ⚙️ Architecture Overview\n\nThe project consists of two main components:\n\n- 🧠 **Backend** — A REST API built with **FastAPI** and packaged as a\n  Python library. The API is created via `trueeye.create_app()` and can be\n  run using `uvicorn`.\n- 🧱 **Frontend** — A minimal static web interface built with TailwindCSS\n  (served from the package's static directory). It allows users to input a\n  URL, trigger analysis and view the result.\n\nThe heavy lifting is performed by a remote LangFlow pipeline via the\n`FLOW_API_URL` environment variable. For offline testing you can set\n`TE_PROVIDER=local` and the API will return a stubbed response.\n\n## 📁 Project Structure\n\n```\nTrueEye_v1/\n├── src/trueeye/\n│   ├── __init__.py      # Exposes create_app()\n│   ├── api.py           # FastAPI application factory and endpoints\n│   ├── models.py        # Pydantic models\n│   ├── utils.py         # Helper functions\n│   └── static/\n│       └── index.html   # Frontend UI\n├── tests/               # Test suite\n├── pyproject.toml       # Project metadata and dependencies\n├── .pre-commit-config.yaml\n├── .github/workflows/ci.yml\n├── CONTRIBUTING.md\n├── CODE_OF_CONDUCT.md\n├── SECURITY.md\n├── LICENSE.txt          # Non‑commercial license\n└── README.md            # Project documentation (this file)\n```\n\n## 💻 Running on NixOS/Nix\n\n### 🚀 Quick Start (One Command)\n\n```bash\n# Option 1: Using start.sh script (recommended)\n./start.sh\n\n# Option 2: Using Makefile\nmake start\n\n# Option 3: Direct Nix command\nnix-shell --run \"trueeye-dev\"\n```\n\n### 🔧 Initial Setup\n\nThe project includes automatic configuration. On first use:\n\n1. An `.env` file will be automatically created from `.env.example`\n2. The Python environment will be configured with all dependencies\n3. The application will start in local mode (no external connection)\n\n### ⚙️ Environment Variables Configuration\n\n```bash\n# To edit configuration:\n./start.sh config\n# or\nmake config\n\n# For manual configuration:\ncp .env.example .env\n# Then edit .env with your favorite editor\n```\n\nMain variables:\n\n- `TE_PROVIDER=local` → Test mode (no external API)\n- `TE_PROVIDER=remote` → Production mode (requires `FLOW_API_URL`)\n- `PORT=8000` → Server port\n- `HOST=0.0.0.0` → Server host\n\n### 🧪 Available Commands\n\n```bash\n# Commands with start.sh:\n./start.sh start    # Start application (default)\n./start.sh test     # Run tests\n./start.sh config   # Edit configuration\n./start.sh shell    # Open development shell\n./start.sh help     # Show help\n\n# Commands with Makefile:\nmake start         # Start application\nmake test          # Run tests\nmake config        # Edit configuration\nmake shell         # Open development shell\nmake clean         # Clean temporary files\nmake check         # Verify configuration\nmake help          # Show help\n```\n\n### 🏗️ Estructura del Proyecto\n\n## 🐚 Nix Development Shell\n\nThe project includes a fully configured `shell.nix` that provides:\n\n- ✅ **Python 3.10+** with all dependencies\n- ✅ **FastAPI and Uvicorn** pre-configured\n- ✅ **Testing tools** (pytest, httpx)\n- ✅ **Development utilities** (mypy, curl, jq)\n- ✅ **Custom scripts** to make usage easy\n- ✅ **Automatic loading** of environment variables\n- ✅ **Automatic PYTHONPATH** configuration\n\n### 💡 Special Features\n\n- **Automatic configuration**: Creates `.env` if it doesn't exist\n- **Environment validation**: Verifies configuration at startup\n- **Multiple interfaces**: Bash script, Makefile, Nix commands\n- **Development mode**: Auto-reload with `--reload`\n- **Integrated testing**: Test suite ready to use\n- **Automatic cleanup**: Temporary file management\n\n### 🎯 Recommended Usage for NixOS\n\n```bash\n# 1. Clone/access the project\ncd /path/to/trueeye_v1\n\n# 2. Run (everything gets configured automatically)\n./start.sh\n\n# 3. Access the application\nfirefox http://localhost:8000\n```\n\n## 🔍 System Verification\n\nTo verify that everything is properly configured:\n\n```bash\n# Verify dependencies and configuration\nmake check\n\n# View environment information\nmake dev-info\n\n# Run tests to validate functionality\n./start.sh test\n```\n\n## 📚 Technologies and Tools\n\n### Backend\n\n- **FastAPI** — High-performance Python web framework\n- **Uvicorn** — ASGI server with asyncio support\n- **Pydantic** — Data validation with type hints\n- **Requests** — HTTP client for API integration\n\n### Frontend\n\n- **HTML5/JavaScript** — Minimal and functional frontend\n- **TailwindCSS** — Utility-first CSS framework\n- **Marked.js** — Markdown processing for responses\n\n### Development\n\n- **Nix/NixOS** — Reproducible environment management\n- **pytest** — Testing framework\n- **mypy** — Static type checking\n- **Shell Scripts** — Task automation\n\n### Integration\n\n- **LangFlow API** — AI analysis pipeline (remote mode)\n- **Local mode** — Stub responses for offline development\n\n## ✍️ Author\n\n**Gonzalo Romero (DeepRat)**\n\nAI, Software \u0026 Systems Engineer · Prompt Engineer · Full‑Stack Developer\n\n🔗 [Web](https://deeprat.tech) | [Hugging Face](https://huggingface.co/DeepRat) | [GitHub](https://github.com/DeepRatAI) | [LinkedIn](https://www.linkedin.com/in/gonzalo-romero-b9b5b4355) | [Medium](https://medium.com/@hermmes.ia)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepratai%2Ftrueeye","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeepratai%2Ftrueeye","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepratai%2Ftrueeye/lists"}