CONTRIBUTING.md

Contributing to Verifacts Backend

Welcome to the Verifacts engineering team! This guide will help you set up your development environment and understand our engineering standards.

🚀 Environment Setup

We use Poetry for dependency management to ensure deterministic builds across all micro-modules.

1. Installation

# Install Project Dependencies
poetry install

2. Configuration

Copy the example environment file:

cp .env.example .env

Required Variables:

• OPENAI_API_KEY: For LLM extraction.
• FIRECRAWL_API_KEY: For web scraping.
• GOOGLE_FACT_CHECK_KEY: For verification.

3. Running the Server

Start the hot-reloading development server:

poetry run uvicorn app.api.server:app --reload

---

🌳 Git Workflow & Branching Strategy

We follow a strict branching model to keep our codebase stable. Never push directly to main.

Branch Naming Convention

• Features: feat/short-description (e.g., feat/add-sentiment-node)
• Bug Fixes: fix/short-description (e.g., fix/firecrawl-timeout)
• Documentation: docs/short-description (e.g., docs/update-api-schema)
• Chore/Refactor: chore/short-description (e.g., chore/bump-poetry-version)

The Workflow

1. Sync with Main:

   git checkout main
   git pull origin main
   

2. Create Branch:

   git checkout -b feat/my-new-feature
   

3. Code & Test: Write your code and ensure poetry run pytest passes.
4. Push & PR: Push your branch and open a Pull Request (PR) for review.

---

📝 Commit Message Standards

We use Conventional Commits to automate our changelogs. Your commit message must look like this:

<type>(<scope>): <short summary>

Types

• feat: A new feature (e.g., adding a new LangGraph node).
• fix: A bug fix.
• docs: Documentation only changes.
• style: Formatting, missing semi-colons, etc. (no code change).
• refactor: A code change that neither fixes a bug nor adds a feature.
• perf: A code change that improves performance.
• test: Adding missing tests.
• chore: Maintainance tasks (e.g., updating .gitignore).

Examples

• ✅ feat(graph): add sentiment analysis node to workflow
• ✅ fix(api): handle 404 error from Firecrawl
• ✅ docs(readme): update setup instructions for Windows
• ❌ Fixed the bug (Too vague)
• ❌ Added new agent (Missing scope)

---

🛠️ How to Add a New Feature (The "Node" Workflow)

Adding intelligence to Veritas means adding a Node to the LangGraph. Follow this 4-step process:

Step 1: Create the Logic (The Module)

Create a new file in app/graph/nodes/. It must accept AgentState and return a dictionary of updates.

• File: app/graph/nodes/sentiment.py
• Function: async def sentiment_node(state: AgentState) -> Dict[str, Any]: ...

Step 2: Update the State

If your node produces new data (e.g., a "sentiment score"), define it in the shared state.

• File: app/graph/state.py
• Action: Add sentiment_score: float to the AgentState TypedDict.

Step 3: Register in the Graph

Wire your new node into the orchestration flow.

• File: app/graph/workflow.py
• Action:
  1. workflow.add_node("sentiment", sentiment_node)
  2. Define when it runs (e.g., workflow.add_edge("reader", "sentiment")).

Step 4: Expose via API (Optional)

If the frontend needs to see this data, update the response model.

• File: app/api/v1/models.py (or server.py)
• Action: Add the field to the Pydantic Response model.

---

🧪 Testing Requirements

Before submitting a PR, ensure you have added tests for your new node.

# Run unit tests
poetry run pytest

# Run linting manually (Recommended)
poetry run ruff check .

Pull Request Reviews

All PRs must be reviewed by at least one other team member. Look for:

• Code quality and adherence to standards.
• Proper testing coverage.
• Clear and descriptive commit messages.

Thank you for contributing to Verifacts! Your efforts help us build a reliable and intelligent verification platform.