Merge pull request #2 from ppl-ai/james/fact-checking-app

james-pplx · web-flow · commit f3bb2b663bda · 2025-03-28T10:26:32.000-04:00
James/fact checking app
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,88 @@
+# API Keys
+pplx_api_key
+.pplx_api_key
+PPLX_API_KEY
+.PPLX_API_KEY
+*.key
+.env
+.env.*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv/
+.env/
+.ENV/
+env.bak/
+venv.bak/
+.python-version
+
+# IDE specific files
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.settings/
 .DS_Store
-**/.DS_Store
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+.tox/
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Project-specific
+article.txt
+claims.txt
+facts.txt
+test_articles/
+results/
+custom_prompt.md
+output.json
+report.json
+
+# OS specific files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
diff --git a/README.md b/README.md
@@ -1,7 +1,76 @@
-**Sonar Cookbook**
+# Sonar API Projects
 
-This Cookbook provides code and guides designed to help developers build with Sonar, offering code snippets that can easily be integrated into your own projects.
+A collection of practical applications and tools built with [Perplexity's Sonar API](https://sonar.perplexity.ai/), the fastest, most cost-effective AI answer engine with robust search capabilities.
 
-**Prerequisites**
+## ⚠️ API Key Required
 
-You'll need an API key (sign up by following the steps [here](https://docs.perplexity.ai/guides/getting-started))
+**Before you begin:** You'll need a Perplexity API key to use any project in this repository. 
+
+Sign up for an API key by following the steps in the [Perplexity documentation](https://docs.perplexity.ai/guides/getting-started).
+
+## About This Repository
+
+This repository contains various projects that demonstrate how to leverage Perplexity's Sonar API for different use cases. Each project is designed to showcase the API's capabilities while providing practical, ready-to-use tools for developers.
+
+## Projects
+
+### Fact Checker CLI
+
+The flagship project in this collection is a command-line tool that analyzes claims or articles for factual accuracy. Using Sonar API's powerful search capabilities, it identifies false or misleading statements, provides corrections, and cites reliable sources.
+
+[Read more about the Fact Checker CLI →](./fact-checker/README.md)
+
+### Coming Soon
+
+We're actively working on adding more projects to this collection:
+
+- **Research Assistant**: Automated literature review and summarization tool
+- **News Analyzer**: Track developing stories and analyze reporting biases
+- **Content Verifier**: Browser extension for real-time fact checking
+- **Data Explorer**: Query and visualize complex datasets through natural language
+
+## Why Sonar API?
+
+Perplexity's Sonar API offers several advantages that make it ideal for building powerful AI applications:
+
+- **Fast & Cost-Effective**: Get reliable answers at a fraction of the cost of other AI APIs
+- **Search Grounding**: Internet-connected models that can access and cite the latest information
+- **Easy Integration**: Simple, straightforward API that developers can integrate in minutes
+- **Scalable Pricing**: Pay-as-you-go model that scales with your usage
+
+## Getting Started
+
+To use any of the projects in this repository, you'll need:
+
+1. A Perplexity API key (sign up [here](https://docs.perplexity.ai/guides/getting-started))
+3. Python 3.7+ installed on your system
+
+Each project includes its own README with specific installation and usage instructions.
+
+## API Access
+
+You can sign up for Perplexity's Sonar API at [sonar.perplexity.ai](https://sonar.perplexity.ai/).
+
+The API offers:
+- Free tier to get started
+- Straightforward documentation
+- Transparent usage-based pricing
+
+## Contributing
+
+Contributions to this repository are welcome! Whether you want to:
+
+- Fix bugs in existing projects
+- Add new features to current tools
+- Contribute entirely new Sonar API projects
+- Improve documentation or examples
+
+Please check the [CONTRIBUTING.md](./CONTRIBUTING.md) file for guidelines.
+
+## License
+
+Unless otherwise specified, all projects in this repository are licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
+
+---
+
+*Build with the best AI answer engine. Power your products with the fastest, cheapest API offering out there with search grounding. Get started in minutes.*
diff --git a/fact_checker_cli/README.md b/fact_checker_cli/README.md
@@ -4,23 +4,22 @@ A command-line tool that identifies false or misleading claims in articles or st
 
 ## Features
 
-- Analyze claims or entire articles for factual accuracy
-- Identify false, misleading, or unverifiable claims
-- Provide explanations and corrections for inaccurate information
-- Output results in human-readable format or structured JSON
-- Cite reliable sources for fact-checking assessments
+- Analyze claims or entire articles for factual accuracy  
+- Identify false, misleading, or unverifiable claims  
+- Provide explanations and corrections for inaccurate information  
+- Output results in human-readable format or structured JSON  
+- Cite reliable sources for fact-checking assessments  
 - Leverages Perplexity's structured outputs for reliable JSON parsing (for Tier 3+ users)
 
 ## Installation
 
-
-1. Install required dependencies:
+### 1. Install required dependencies
 
 ```bash
 pip install requests pydantic
 ```
 
-2. Make the script executable:
+### 2. Make the script executable
 
 ```bash
 chmod +x fact_checker.py
@@ -30,95 +29,110 @@ chmod +x fact_checker.py
 
 The tool requires a Perplexity API key to function. You can provide it in one of these ways:
 
-1. As a command-line argument: `--api-key YOUR_API_KEY`
-2. As an environment variable: `export PPLX_API_KEY=YOUR_API_KEY`
-3. In a file named `pplx_api_key` or `.pplx_api_key` in the same directory as the script:
+### 1. As a command-line argument
+
+```bash
+./fact_checker.py --api-key YOUR_API_KEY
+```
+
+### 2. As an environment variable
+
+```bash
+export PPLX_API_KEY=YOUR_API_KEY
+```
+
+### 3. In a file
+
+Create a file named `pplx_api_key` or `.pplx_api_key` in the same directory as the script:
 
 ```bash
-# Create a file to store your API key
 echo "YOUR_API_KEY" > .pplx_api_key
-# Make sure to protect your API key
 chmod 600 .pplx_api_key
 ```
 
 **Note:** If you're using the structured outputs feature, you'll need a Perplexity API account with Tier 3 or higher access level.
 
 ## Quick Start
 
-Here's a command you can copy and run immediately after setup:
+Run the following command immediately after setup:
 
 ```bash
-# Make sure your API key is set up as described above, then run:
 ./fact_checker.py -t "The Earth is flat and NASA is hiding the truth."
 ```
 
 This will analyze the claim, research it using Perplexity's Sonar API, and return a detailed fact check with ratings, explanations, and sources.
 
 ## Usage
 
-### Basic Usage
-
-Check a claim:
+### Check a claim
 
 ```bash
 ./fact_checker.py --text "The Earth is flat and NASA is hiding the truth."
 ```
 
-### Check an article from a file:
+### Check an article from a file
 
 ```bash
 ./fact_checker.py --file article.txt
 ```
 
-### Specify a different model:
+### Specify a different model
 
 ```bash
 ./fact_checker.py --text "Global temperatures have decreased over the past century." --model "sonar-pro"
 ```
 
-### Output results as JSON:
+### Output results as JSON
 
 ```bash
 ./fact_checker.py --text "Mars has a breathable atmosphere." --json
 ```
 
-### Use a custom prompt file:
+### Use a custom prompt file
 
 ```bash
 ./fact_checker.py --text "The first human heart transplant was performed in the United States." --prompt-file custom_prompt.md
 ```
 
-### Disable structured outputs (for lower tier accounts):
+### Enable structured outputs (for Tier 3+ users)
+
+Structured output is disabled by default. To enable it, pass the `--structured-output` flag:
 
 ```bash
-./fact_checker.py --text "Vaccines cause autism." --no-structured-output
+./fact_checker.py --text "Vaccines cause autism." --structured-output
 ```
 
-### Get help:
+### Get help
 
 ```bash
 ./fact_checker.py --help
 ```
 
 ## Output Format
 
-The tool provides a structured output with:
+The tool provides output including:
 
-- Overall rating of the content (MOSTLY_TRUE, MIXED, or MOSTLY_FALSE)
-- Summary of findings
-- List of specific claims with individual ratings:
+- **Overall Rating**: MOSTLY_TRUE, MIXED, or MOSTLY_FALSE
+- **Summary**: A brief overview of the fact-checking findings
+- **Claims Analysis**: A list of specific claims with individual ratings:
   - TRUE: Factually accurate and supported by evidence
   - FALSE: Contradicted by evidence
-  - MISLEADING: Contains some truth but presented in a way that could lead to incorrect conclusions
+  - MISLEADING: Contains some truth but could lead to incorrect conclusions
   - UNVERIFIABLE: Cannot be conclusively verified with available information
-- Explanations for each claim
-- Sources used for verification
+- **Explanations**: Detailed reasoning for each claim
+- **Sources**: Citations and URLs used for verification
 
 ## Example
 
+Run the following command:
+
+```bash
+./fact_checker.py -t "The Great Wall of China is visible from the moon."
 ```
-$ ./fact_checker.py -t "The Great Wall of China is visible from the moon."
 
+Example output:
+
+```
 Fact checking in progress...
 
 🔴 OVERALL RATING: MOSTLY_FALSE
@@ -128,9 +142,9 @@ The claim that the Great Wall of China is visible from the moon is false. This i
 
 🔍 CLAIMS ANALYSIS:
 
-Claim 1: ❌ FALSE
-  Statement: "The Great Wall of China is visible from the moon."
-  Explanation: The Great Wall of China is not visible from the moon with the naked eye. NASA astronauts have confirmed this, including Neil Armstrong who stated he could not see the Wall from lunar orbit. The Wall is too narrow and is similar in color to its surroundings when viewed from such a distance.
+Claim 1: ❌ FALSE  
+  Statement: "The Great Wall of China is visible from the moon."  
+  Explanation: The Great Wall of China is not visible from the moon with the naked eye. NASA astronauts have confirmed this, including Neil Armstrong who stated he could not see the Wall from lunar orbit. The Wall is too narrow and is similar in color to its surroundings when viewed from such a distance.  
   Sources:
     - NASA.gov
     - Scientific American
@@ -139,7 +153,7 @@ Claim 1: ❌ FALSE
 
 ## Limitations
 
-- The accuracy of fact-checking depends on the quality of information available through the Perplexity Sonar API
-- Like all language models, the underlying AI may have limitations in certain specialized domains
-- The structured outputs feature requires a Tier 3 or higher Perplexity API account
-- The tool does not replace professional fact-checking services for highly sensitive or complex content
+- The accuracy of fact-checking depends on the quality of information available through the Perplexity Sonar API.
+- Like all language models, the underlying AI may have limitations in certain specialized domains.
+- The structured outputs feature requires a Tier 3 or higher Perplexity API account.
+- The tool does not replace professional fact-checking services for highly sensitive or complex content.
diff --git a/fact_checker_cli/fact_checker.py b/fact_checker_cli/fact_checker.py
