Feat/addsdocs

docs/contributing.md → CONTRIBUTING.md

@@ -12,7 +12,14 @@ Thank you for your interest in contributing to The DETERMINATOR! This guide will
 - [Key Principles](#key-principles)
 - [Pull Request Process](#pull-request-process)
 
-> **Note**: Additional sections (Code Style, Error Handling, Testing, Implementation Patterns, Code Quality, and Prompt Engineering) are available as separate pages in the navigation sidebar.
+> **Note**: Additional sections (Code Style, Error Handling, Testing, Implementation Patterns, Code Quality, and Prompt Engineering) are available as separate pages in the [documentation](https://deepcritical.github.io/GradioDemo/contributing/).  
+> **Note on Project Names**: "The DETERMINATOR" is the product name, "DeepCritical" is the organization/project name, and "determinator" is the Python package name.
+
+## Repository Information
+
+- **GitHub Repository**: [`DeepCritical/GradioDemo`](https://github.com/DeepCritical/GradioDemo) (source of truth, PRs, code review)
+- **HuggingFace Space**: [`DataQuests/DeepCritical`](https://huggingface.co/spaces/DataQuests/DeepCritical) (deployment/demo)
+- **Package Name**: `determinator` (Python package name in `pyproject.toml`)
 
 ## Git Workflow
 
@@ -22,9 +29,31 @@ Thank you for your interest in contributing to The DETERMINATOR! This guide will
 - **NEVER** push directly to `main` or `dev` on HuggingFace
 - GitHub is source of truth; HuggingFace is for deployment
 
+### Dual Repository Setup
+
+This project uses a dual repository setup:
+
+- **GitHub (`DeepCritical/GradioDemo`)**: Source of truth for code, PRs, and code review
+- **HuggingFace (`DataQuests/DeepCritical`)**: Deployment target for the Gradio demo
+
+#### Remote Configuration
+
+When cloning, set up remotes as follows:
+
+```bash
+# Clone from GitHub
+git clone https://github.com/DeepCritical/GradioDemo.git
+cd GradioDemo
+
+# Add HuggingFace remote (optional, for deployment)
+git remote add huggingface-upstream https://huggingface.co/spaces/DataQuests/DeepCritical
+```
+
+**Important**: Never push directly to `main` or `dev` on HuggingFace. Always work through GitHub PRs. GitHub is the source of truth; HuggingFace is for deployment/demo only.
+
 ## Getting Started
 
-1. **Fork the repository** on GitHub
+1. **Fork the repository** on GitHub: [`DeepCritical/GradioDemo`](https://github.com/DeepCritical/GradioDemo)
 2. **Clone your fork**:
 
    ```bash
@@ -35,7 +64,8 @@ Thank you for your interest in contributing to The DETERMINATOR! This guide will
 3. **Install dependencies**:
 
    ```bash
-   make install
+   uv sync --all-extras
+   uv run pre-commit install
    ```
 
 4. **Create a feature branch**:
@@ -48,7 +78,9 @@ Thank you for your interest in contributing to The DETERMINATOR! This guide will
 6. **Run checks**:
 
    ```bash
-   make check
+   uv run ruff check src tests
+   uv run mypy src
+   uv run pytest --cov=src --cov-report=term-missing tests/unit/ -v -m "not openai" -p no:logfire
    ```
 
 7. **Commit and push**:
@@ -57,22 +89,72 @@ Thank you for your interest in contributing to The DETERMINATOR! This guide will
    git commit -m "Description of changes"
    git push origin yourname-feature-name
    ```
+
 8. **Create a pull request** on GitHub
 
+## Package Manager
+
+This project uses [`uv`](https://github.com/astral-sh/uv) as the package manager. All commands should be prefixed with `uv run` to ensure they run in the correct environment.
+
+### Installation
+
+```bash
+# Install uv if you haven't already (recommended: standalone installer)
+# Unix/macOS/Linux:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows (PowerShell):
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# Alternative: pipx install uv
+# Or: pip install uv
+
+# Sync all dependencies including dev extras
+uv sync --all-extras
+
+# Install pre-commit hooks
+uv run pre-commit install
+```
+
 ## Development Commands
 
 ```bash
-make install      # Install dependencies + pre-commit
-make check        # Lint + typecheck + test (MUST PASS)
-make test         # Run unit tests
-make lint         # Run ruff
-make format       # Format with ruff
-make typecheck    # Run mypy
-make test-cov     # Test with coverage
-make docs-build  # Build documentation
-make docs-serve  # Serve documentation locally
+# Installation
+uv sync --all-extras              # Install all dependencies including dev
+uv run pre-commit install          # Install pre-commit hooks
+
+# Code Quality Checks (run all before committing)
+uv run ruff check src tests       # Lint with ruff
+uv run ruff format src tests      # Format with ruff
+uv run mypy src                   # Type checking
+uv run pytest --cov=src --cov-report=term-missing tests/unit/ -v -m "not openai" -p no:logfire  # Tests with coverage
+
+# Testing Commands
+uv run pytest tests/unit/ -v -m "not openai" -p no:logfire              # Run unit tests (excludes OpenAI tests)
+uv run pytest tests/ -v -m "huggingface" -p no:logfire                 # Run HuggingFace tests
+uv run pytest tests/ -v -p no:logfire                                  # Run all tests
+uv run pytest --cov=src --cov-report=term-missing tests/unit/ -v -m "not openai" -p no:logfire  # Tests with terminal coverage
+uv run pytest --cov=src --cov-report=html -p no:logfire                # Generate HTML coverage report (opens htmlcov/index.html)
+
+# Documentation Commands
+uv run mkdocs build                # Build documentation
+uv run mkdocs serve                # Serve documentation locally (http://127.0.0.1:8000)
 ```
 
+### Test Markers
+
+The project uses pytest markers to categorize tests. See [Testing Guidelines](docs/contributing/testing.md) for details:
+
+- `unit`: Unit tests (mocked, fast)
+- `integration`: Integration tests (real APIs)
+- `slow`: Slow tests
+- `openai`: Tests requiring OpenAI API key
+- `huggingface`: Tests requiring HuggingFace API key
+- `embedding_provider`: Tests requiring API-based embedding providers
+- `local_embeddings`: Tests using local embeddings
+
+**Note**: The `-p no:logfire` flag disables the logfire plugin to avoid conflicts during testing.
+
 ## Code Style & Conventions
 
 ### Type Safety
@@ -118,10 +200,10 @@ result = await loop.run_in_executor(None, cpu_bound_function, args)
 
 ### Pre-commit
 
-- Run `make check` before committing
+- Pre-commit hooks run automatically on commit
 - Must pass: lint + typecheck + test-cov
-- Pre-commit hooks installed via `make install`
-- **CRITICAL**: Make sure you run the full pre-commit checks before opening a PR (not draft), otherwise Obstacle is the Way will lose his mind
+- Install hooks with: `uv run pre-commit install`
+- Note: `uv sync --all-extras` installs the pre-commit package, but you must run `uv run pre-commit install` separately to set up the git hooks
 
 ## Error Handling & Logging
 
@@ -191,7 +273,7 @@ except httpx.HTTPError as e:
 1. Write failing test in `tests/unit/`
 2. Implement in `src/`
 3. Ensure test passes
-4. Run `make check` (lint + typecheck + test)
+4. Run checks: `uv run ruff check src tests && uv run mypy src && uv run pytest --cov=src --cov-report=term-missing tests/unit/ -v -m "not openai" -p no:logfire`
 
 ### Test Examples
 
@@ -212,7 +294,8 @@ async def test_real_pubmed_search():
 
 ### Test Coverage
 
-- Run `make test-cov` for coverage report
+- Run `uv run pytest --cov=src --cov-report=term-missing tests/unit/ -v -m "not openai" -p no:logfire` for coverage report
+- Run `uv run pytest --cov=src --cov-report=html -p no:logfire` for HTML coverage report (opens `htmlcov/index.html`)
 - Aim for >80% coverage on critical paths
 - Exclude: `__init__.py`, `TYPE_CHECKING` blocks
 
@@ -385,19 +468,27 @@ Example:
 
 ## Pull Request Process
 
-1. Ensure all checks pass: `make check`
+1. Ensure all checks pass: `uv run ruff check src tests && uv run mypy src && uv run pytest --cov=src --cov-report=term-missing tests/unit/ -v -m "not openai" -p no:logfire`
 2. Update documentation if needed
 3. Add tests for new features
 4. Update CHANGELOG if applicable
 5. Request review from maintainers
 6. Address review feedback
 7. Wait for approval before merging
 
+## Project Structure
+
+- `src/`: Main source code
+- `tests/`: Test files (`unit/` and `integration/`)
+- `docs/`: Documentation source files (MkDocs)
+- `examples/`: Example usage scripts
+- `pyproject.toml`: Project configuration and dependencies
+- `.pre-commit-config.yaml`: Pre-commit hook configuration
+
 ## Questions?
 
-- Open an issue on GitHub
-- Check existing documentation
+- Open an issue on [GitHub](https://github.com/DeepCritical/GradioDemo)
+- Check existing [documentation](https://deepcritical.github.io/GradioDemo/)
 - Review code examples in the codebase
 
-Thank you for contributing to DeepCritical!
-
+Thank you for contributing to The DETERMINATOR!