Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
241 lines (181 loc) · 6.62 KB

CONTRIBUTING.md

File metadata and controls

241 lines (181 loc) · 6.62 KB
Raw

Contributing to DocuChat

First off, thank you for considering contributing to DocuChat! It's people like you that make DocuChat a great tool for the community.

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, include as many details as possible:

Use the bug report template and include:

  • A clear and descriptive title
  • Exact steps to reproduce the problem
  • Expected vs actual behavior
  • System information (OS, Python version, hardware specs)
  • Relevant logs from ~/.docuchat/logs/

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:

  • Use a clear and descriptive title
  • Provide a detailed description of the proposed functionality
  • Explain why this enhancement would be useful
  • Include code examples or mockups if applicable

Pull Requests

  1. Fork and Clone

    git clone git@github.com:YOUR_USERNAME/docuchat-agent_cli.git
cd docuchat-agent_cli

  2. Set Up Development Environment

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

  3. Create a Branch

    git checkout -b feature/amazing-feature
# or
git checkout -b fix/bug-description

  4. Make Your Changes

    • Follow the project structure in docuchat/
    • Write clear, self-documenting code
    • Add docstrings to all functions and classes
    • Follow single responsibility principle

  5. Test Your Changes

    # Run integration tests
python -m pytest tests/integration/

# Test CLI commands manually
docuchat ingest test_documents/
docuchat chat
docuchat status

  6. Commit Your Changes

    git add .
git commit -m "feat: add amazing feature

- Detailed description of changes
- Why this change is needed
- Any breaking changes or migration notes"

    Commit Message Format:

    • feat: - New feature
    • fix: - Bug fix
    • docs: - Documentation changes
    • refactor: - Code refactoring
    • test: - Adding tests
    • perf: - Performance improvements
    • chore: - Maintenance tasks

  7. Push to Your Fork

    git push origin feature/amazing-feature

  8. Open a Pull Request

    • Use the PR template
    • Link related issues
    • Provide clear description of changes
    • Add screenshots/examples if relevant

Development Guidelines

Project Structure

docuchat/
├── cli/              # Command-line interface - Click commands
├── core/             # Business logic - Document processing, embeddings
├── agents/           # LangGraph workflow - RAG pipeline nodes
├── integrations/     # External services - ChromaDB, Neo4j, Ollama
├── models/           # Data models - Pydantic schemas
├── utils/            # Utilities - Hardware detection, text processing
└── config/           # Configuration - Settings, hardware config

Code Style

  • Python Version: 3.10+
  • Style Guide: PEP 8
  • Formatting: Black (line length 100)
  • Type Hints: Use type annotations for all functions
  • Docstrings: Google style docstrings

Example:

from typing import List, Optional

def process_documents(
    file_paths: List[str],
    chunk_size: int = 512,
    overlap: int = 50
) -> List[Document]:
    """Process documents into chunks with entity-aware boundaries.

    Args:
        file_paths: Paths to documents to process
        chunk_size: Maximum characters per chunk
        overlap: Character overlap between chunks

    Returns:
        List of processed Document objects with metadata

    Raises:
        DocumentProcessingError: If file cannot be processed
    """
    # Implementation

Testing

  • Write integration tests for new features
  • Test CLI commands end-to-end
  • Verify database interactions (ChromaDB + Neo4j)
  • Test with different LLM models (Ollama + Gemini)

Performance Considerations

  • Target hardware: Intel i7-6500U (2 cores, 4 threads)
  • Memory budget: ≤5.5GB with models loaded
  • Query response: 2-5 seconds target
  • Use ONNX optimization where applicable

Documentation

  • Update docs/architecture.md for architectural changes
  • Update README.md for user-facing changes
  • Add examples to examples/ directory if relevant
  • Update CHANGELOG.md following Keep a Changelog format

Areas Where We Need Help

High Priority

  • Web UI/Dashboard - React/Vue frontend for document management
  • Additional LLM Integrations - OpenAI, Anthropic, local models
  • OCR Improvements - Better scanned document handling
  • Mobile Support - iOS/Android document ingestion

Medium Priority

  • Performance Optimization - Faster embedding generation
  • Additional File Formats - Excel, PowerPoint, CSV
  • Export Features - Export knowledge graphs, chat history
  • Plugin System - Extensible architecture for custom processors

Documentation

  • Video tutorials for setup and usage
  • More example use cases and workflows
  • API documentation improvements
  • Troubleshooting guides

Recognition

Contributors will be:

  • Added to CONTRIBUTORS.md
  • Mentioned in release notes for significant contributions
  • Credited in the README for major features

Questions?

  • Open a GitHub Discussion
  • Check existing documentation in docs/
  • Review architecture guide: docs/architecture.md

Development Resources

Useful Commands

# Start services
./setup_docuchat.sh

# Check system health
docuchat status --check-services

# Reset for clean testing
docuchat reset-all

# View logs
tail -f ~/.docuchat/logs/docuchat.log

Key Files to Understand

  • docuchat/agents/rag_workflow.py - Main RAG pipeline (LangGraph)
  • docuchat/core/document_processor.py - Document ingestion logic
  • docuchat/integrations/chroma_client.py - Vector database client
  • docuchat/integrations/neo4j_client.py - Graph database client
  • docuchat/cli/chat.py - Interactive chat interface

External Dependencies

  • ChromaDB - Vector embeddings (port 8000)
  • Neo4j - Knowledge graph (bolt://localhost:7687)
  • Ollama - Local LLM inference (port 11434)
  • spaCy - NLP entity extraction (en_core_web_sm model)

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for making DocuChat better! 🚀