Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
157 lines (113 loc) · 4.89 KB

CONTRIBUTING.md

File metadata and controls

157 lines (113 loc) · 4.89 KB

Contributing to AbstractCore

Thanks for contributing to AbstractCore. This guide is written for external contributors and focuses on a fast setup, practical repo conventions, and a smooth PR process.

Quick start

git clone https://github.com/lpalbou/AbstractCore.git
cd AbstractCore

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
python -m pip install -U pip

# Tooling + tests (recommended baseline for contributors)
pip install -e ".[dev,test]"

pytest -q

Optional extras (install only what you need)

AbstractCore’s default install is intentionally lightweight. Most features and provider SDKs are behind extras:

pip install -e ".[remote]"       # OpenAI + Anthropic SDKs (OpenRouter/Portkey use core httpx)
pip install -e ".[openai]"       # OpenAI SDK
pip install -e ".[anthropic]"    # Anthropic SDK
pip install -e ".[tools]"        # requests/bs4/lxml/ddgs for built-in tools
pip install -e ".[media]"        # Pillow + PDF/Office extraction
pip install -e ".[embeddings]"   # sentence-transformers + numpy
pip install -e ".[server]"       # FastAPI gateway

Extras compose, so a realistic app setup might be pip install -e ".[remote,tools,media,server]".

If you want a “kitchen sink” contributor environment, full-dev is a convenient superset, but it may not install everywhere (for example MLX vs CUDA-only stacks):

pip install -e ".[full-dev]"

Repository conventions

Dependency and import-safety policy (important)

AbstractCore is designed so:

  • pip install abstractcore stays small.
  • import abstractcore stays import-safe.

When contributing:

  • Don’t add heavy libraries to core dependencies in pyproject.toml.
  • Keep optional subsystems behind explicit extras ([tools], [media], [embeddings], [server], provider SDKs).
  • Avoid importing optional dependencies on default import paths (for example abstractcore/__init__.py). Prefer lazy imports and clear install hints like pip install "abstractcore[media]".

Formatting, linting, and typing

These tools are useful, but the full-repo baselines are not currently clean. Treat them as diagnostics unless a maintainer explicitly asks for a full-repo cleanup.

  • black is the code formatter. It rewrites layout/spacing; most failures are style drift, not runtime bugs.
  • ruff is the fast linter. Some findings are cosmetic, but F821 undefined names, broad except, unused imports, and similar findings can point to real bugs.
  • mypy is the static type checker. The repo has a strict target config, but dynamic provider code and optional dependencies still produce known legacy errors.

For normal PRs, format and lint the files you touched when they already have a clean local baseline:

black path/to/changed_file.py
ruff check path/to/changed_file.py

If a touched file has legacy style/lint debt, avoid unrelated churn and keep the high-signal package check clean:

ruff check --select F821 abstractcore

Full-repo checks are still useful for maintainers tracking cleanup progress:

black --check abstractcore tests
ruff check abstractcore
mypy abstractcore

Pre-commit (recommended)

This repo has pre-commit hooks for formatting/lint checks. The expensive hooks are configured for manual use, so run them explicitly when you want them.

One-time setup:

pip install -e ".[dev,test]"
pre-commit install

Run on all files:

pre-commit run --all-files

Tests

pytest -q

Some provider-/network-/hardware-dependent tests are intentionally opt-in and may skip locally. When local LLM services or heavyweight inference tests are enabled, the suite can take a long time; during development, run the focused test file or marker first, then a broader pass before release. See tests/README_VISION_TESTING.md and tests/README_SEED_TESTING.md.

Documentation

If a change affects user-facing behavior, update the docs entry points:

  • README.md
  • docs/README.md
  • docs/getting-started.md
  • docs/architecture.md
  • docs/api.md
  • docs/faq.md
  • docs/server.md (if the HTTP gateway is affected)

Keep language clear, user-oriented, and accurate to the code (the code is the source of truth).

Pull request checklist

  • Add or update tests where appropriate.
  • Run relevant tests; run pytest -q when feasible.
  • Run black and ruff check on changed files.
  • Keep ruff check --select F821 abstractcore passing.
  • Update relevant documentation.
  • Add a changelog entry when the change is user-visible.

Versioning (maintainers)

The package version is sourced from abstractcore/utils/version.py.

For a release:

  1. Bump abstractcore/utils/version.py.
  2. Add a new section to CHANGELOG.md.
  3. Verify: python -c "import abstractcore; print(abstractcore.__version__)"

Security

If you believe you found a security vulnerability, please follow SECURITY.md for responsible disclosure.