Skip to content

Contributing

Thank you for considering contributing to the Nobel Prize Knowledge Graph project!

Development Setup

Prerequisites

  • Python >= 3.12
  • uv package manager
  • OpenAI API key (for LLM features)

Setup

git clone https://github.com/example/nobel-kg.git
cd nobel-kg
uv sync
cp .env.example .env  # Configure your API keys

Project Structure

src/
├── __init__.py           # Shared config loader
├── data_loader.py        # Phase 1: Data loading
├── content_enricher.py   # Phase 1.5: Content enrichment
├── openalex_enricher.py  # Phase 2a: OpenAlex enrichment
├── concept_extractor.py  # Phase 2b: LLM extraction
├── graph_builder.py      # Phase 3+4: Graph construction
├── visualize.py          # Phase 5: Visualization
└── insight_analyzer.py   # Phase 6: Analysis

Coding Conventions

Style

  • Follow PEP 8 style guidelines
  • Use type hints for function signatures
  • Add docstrings to all public functions
  • Use Polars for DataFrame operations (preferred over Pandas)

Module Pattern

Each module follows a consistent pattern:

"""Module description."""

from src import load_config, ROOT_DIR

def process_data(...):
    """Process description."""
    ...

def run():
    """Entry point for this phase."""
    cfg = load_config()
    ...

if __name__ == "__main__":
    run()

API Caching

All external API calls must be cached:

cache_path = Path(cache_dir) / f"{sanitized_id}.json"
if cache_path.exists():
    return json.loads(cache_path.read_text())

# ... make API call ...

cache_path.write_text(json.dumps(result))

Adding a New Pipeline Phase

  1. Create src/new_module.py following the module pattern above
  2. Add the phase to main.py in the appropriate position
  3. Update config/settings.yaml if new configuration is needed
  4. Add documentation in docs/src/en/pipeline/ and docs/src/zh/pipeline/
  5. Add API reference in docs/src/en/api/ and docs/src/zh/api/

Documentation

Building Docs

cd docs
pip install -r requirements.txt
mkdocs serve     # Local preview at http://localhost:8000
mkdocs build     # Build static site to docs/site/

Adding Documentation

  • English docs go in docs/src/en/
  • Chinese docs go in docs/src/zh/
  • Both versions should have the same structure and content

Reporting Issues

When reporting issues, please include:

  1. What you were trying to do
  2. What happened instead
  3. Steps to reproduce
  4. Python version and OS
  5. Relevant log output