Contributing Guide & Code of Conduct

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• README.md
• pyproject.toml
• codecov.yml

The am_diag project provides a framework for Agentic GraphRAG in medical diagnosis. This guide establishes the standards for community interaction and the technical requirements for contributing to the codebase. It ensures that all contributions—ranging from new corpus loaders and evaluation datasets to retrieval components and bug fixes—align with the project's architectural principles and community values.

Sources: CONTRIBUTING.md:3-5, README.md:10-15

Code of Conduct

The project adheres to the Contributor Covenant to foster an inclusive, healthy, and harassment-free community. This applies to all community spaces and public representations of the project.

Community Standards

Positive behavior is encouraged through empathy, kindness, and respect for differing viewpoints. Unacceptable behavior includes harassment, derogatory comments, personal attacks, and the publication of private information without permission.

Sources: CODE_OF_CONDUCT.md:3-36

Enforcement and Responsibilities

Community leaders are responsible for enforcing these standards. They have the right to remove or reject contributions not aligned with the Code of Conduct. Violations can be reported to avnlp400@gmail.com.

The following diagram illustrates the enforcement ladder used by community leaders:

Development Environment Setup

The project utilizes uv for dependency management and requires Python version 3.11 or higher.

Installation Workflow

1. Clone: Fork and clone the repository.
2. Sync: Use make sync to install dependencies via uv.
3. Hooks: Install pre-commit hooks using uv run pre-commit install.
4. Environment: Configure credentials in a .env file (based on .env.example).

Sources: CONTRIBUTING.md:9-24, pyproject.toml:7-9

Required External Services

Integration tests and pipelines require active instances of:

• Neo4j: Graph database.
• Qdrant or Weaviate: Vector stores.
• LLM Endpoint: OpenAI-compatible API.

Sources: CONTRIBUTING.md:21-23, README.md:150-160

Project Architecture & Conventions

The repository follows a flat layout. Contributors must adhere to specific architectural rules to maintain system integrity.

Architecture Rules

• Domain Models: All models must reside in am_diag/common/data_models.
• Cypher Queries: Multi-line Cypher strings are prohibited in Python files. Queries must be externalized in .cypher files under am_diag/common/cypher/.
• Async API: Every public component API must be asynchronous.
• Configuration: Components use pydantic_settings.BaseSettings with environment variable prefixes (e.g., NEO4J_, RETRIEVAL_).

Sources: CONTRIBUTING.md:30-58

Directory Map

Path	Responsibility
am_diag/common/	Data models, Cypher queries, and Graph Schemas.
am_diag/graph_construction/	Extraction, normalization, and community detection logic.
am_diag/ingestion/	LangGraph pipelines for data processing.
am_diag/retrieval/	Search engines, rerankers, and retrieval recipes.
am_diag/llm/	BAML sources and generated typed clients.

Sources: CONTRIBUTING.md:30-45, README.md:330-345

Development Workflow

Tooling and Quality Control

The project uses specific tools for linting, formatting, and type checking:

• Ruff: Formatting and linting (run via make lint-fmt).
• ty: Type checking (run via make lint-typing).
• BAML: LLM function generation. If .baml files are edited, the client must be regenerated using make baml-gen.

Sources: CONTRIBUTING.md:47-75, pyproject.toml:57-75

Testing Standards

Tests mirror the am_diag/ package structure and are executed using pytest.

Pull Request Process

1. Create a feature branch (e.g., feat/, fix/).
2. Implement changes with Google-style docstrings.
3. Pass make lint-all and make test.
4. Update relevant documentation in docs/.
5. Submit PR against main with a clear description.

Sources: CONTRIBUTING.md:109-117

Continuous Integration & Coverage

The project uses GitHub Actions and Codecov to maintain code quality.

• CI Enforcement: CI must pass before merging.
• Coverage Target: The project targets a minimum of 80% patch coverage.
• Exclusions: Tests and BAML-generated files are ignored in coverage reporting to ensure focus on core logic.

Sources: codecov.yml:1-35, pyproject.toml:205-215

Contributing to am_diag requires adherence to strict architectural boundaries and community standards to ensure the medical diagnosis system remains robust, type-safe, and inclusive.