From c02f1268711cbfc6863bebfcd06fbb11e04974d4 Mon Sep 17 00:00:00 2001 From: Ankit Kotnala Date: Sat, 2 May 2026 12:13:45 +0530 Subject: [PATCH 1/4] docs: add contributor onboarding guide --- CONTRIBUTING.md | 171 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ace6f02 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,171 @@ +# Contributing to XMem + +Thanks for helping improve XMem. This guide explains how to set up the project, +make changes safely, and open a pull request that maintainers can review quickly. + +## Before You Start + +- Check the issue list and comment on the issue you want to work on. +- For larger changes, share your approach before opening a PR. +- Keep each PR focused on one bug, feature, or documentation task. +- Do not commit secrets, local `.env` files, generated caches, or API keys. + +## Project Areas + +This repository contains the Python backend, agents, storage integrations, API +routes, scanner, and tests. + +Common areas: + +- `src/agents/` - classifier, memory extraction, judge, and domain agents. +- `src/pipelines/` - ingestion, retrieval, and weaver workflows. +- `src/api/` - FastAPI application, routes, dependencies, and middleware. +- `src/storage/` - vector store interface and Pinecone implementation. +- `src/graph/` - Neo4j clients and graph schemas. +- `src/scanner/` and `src/scanner_v1/` - repository indexing and AST parsing. +- `src/schemas/` - Pydantic models used across agents and APIs. +- `tests/` - unit and integration tests. +- `docs/` - user and developer documentation. + +Related ecosystem pieces such as SDKs, MCP integrations, extensions, and landing +pages may live in separate repositories. Follow the README in that component +when working outside this backend repo. + +## Development Setup + +Requirements: + +- Python 3.11 or newer. +- Access to any external services needed by the area you are testing, such as + Pinecone, Neo4j, MongoDB, or an LLM provider. + +Create and activate a virtual environment: + +```powershell +python -m venv .venv +.venv\Scripts\activate +``` + +On macOS or Linux, use: + +```bash +python -m venv .venv +source .venv/bin/activate +``` + +Install the project with development dependencies: + +```bash +pip install -e ".[dev]" +``` + +Create a local environment file: + +```powershell +copy .env.example .env +``` + +On macOS or Linux, use: + +```bash +cp .env.example .env +``` + +Fill in only the keys needed for your work. For unit tests that do not call real +services, dummy values are often enough. + +## Running Locally + +Start the API server: + +```bash +uvicorn src.api.app:create_app --factory --host 0.0.0.0 --port 8000 +``` + +If you need the full local stack, use the Docker Compose files in `docker/`. + +## Testing + +Run the test suite: + +```bash +pytest +``` + +Run a specific test file: + +```bash +pytest tests/test_deterministic_memory_layer.py +``` + +The project config enables coverage by default. If your local environment does +not have `pytest-cov`, install the dev dependencies again: + +```bash +pip install -e ".[dev]" +``` + +## Linting and Formatting + +Run Ruff before opening a PR: + +```bash +ruff check src tests +``` + +Use the existing project style: + +- Prefer small, focused functions. +- Keep domain schemas in `src/schemas/`. +- Keep prompt text in `src/prompts/`. +- Keep storage writes inside the Weaver or store clients. +- Avoid broad refactors in bug-fix PRs. + +## Coding Standards + +- Use Pydantic models for structured data crossing agent, API, or pipeline + boundaries. +- Keep agent outputs explicit and validated where possible. +- Make Judge logic deterministic when the domain has stable identity keys. +- Keep external service calls behind small wrappers so tests can use fakes. +- Add tests for new behavior, regressions, and failure paths. +- Preserve backward compatibility for existing stored records and API responses. + +## Documentation Standards + +- Keep setup instructions copy-pasteable. +- Prefer short examples over long explanations. +- Update docs when changing public behavior, configuration, or setup steps. +- Do not include real credentials, private URLs, or personal tokens in docs. + +## Pull Request Checklist + +Before submitting: + +- Rebase or sync with the latest main branch. +- Keep the PR scoped to the issue. +- Add or update tests when behavior changes. +- Run relevant tests and lint checks locally. +- Update docs if setup, API behavior, or configuration changes. +- Describe what changed, why it changed, and how you verified it. + +Suggested PR description: + +```md +## Summary +- ... + +## Testing +- ... + +## Notes +- ... +``` + +## Review Process + +Maintainers may ask for changes to scope, tests, naming, or compatibility. Please +respond in the PR thread and push follow-up commits to the same branch. + +For security issues, do not open a public issue with exploit details. Contact the +maintainers privately first. From 4f6c83e2ce829b235178bf171e27def49c250e4e Mon Sep 17 00:00:00 2001 From: Ankit Kotnala Date: Tue, 5 May 2026 20:37:46 +0530 Subject: [PATCH 2/4] Remove local setup and testing instructions from CONTRIBUTING.md Removed sections on creating environment files, running locally, testing, and review process from CONTRIBUTING.md. --- CONTRIBUTING.md | 54 ------------------------------------------------- 1 file changed, 54 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ace6f02..bdce6f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,52 +59,6 @@ Install the project with development dependencies: pip install -e ".[dev]" ``` -Create a local environment file: - -```powershell -copy .env.example .env -``` - -On macOS or Linux, use: - -```bash -cp .env.example .env -``` - -Fill in only the keys needed for your work. For unit tests that do not call real -services, dummy values are often enough. - -## Running Locally - -Start the API server: - -```bash -uvicorn src.api.app:create_app --factory --host 0.0.0.0 --port 8000 -``` - -If you need the full local stack, use the Docker Compose files in `docker/`. - -## Testing - -Run the test suite: - -```bash -pytest -``` - -Run a specific test file: - -```bash -pytest tests/test_deterministic_memory_layer.py -``` - -The project config enables coverage by default. If your local environment does -not have `pytest-cov`, install the dev dependencies again: - -```bash -pip install -e ".[dev]" -``` - ## Linting and Formatting Run Ruff before opening a PR: @@ -161,11 +115,3 @@ Suggested PR description: ## Notes - ... ``` - -## Review Process - -Maintainers may ask for changes to scope, tests, naming, or compatibility. Please -respond in the PR thread and push follow-up commits to the same branch. - -For security issues, do not open a public issue with exploit details. Contact the -maintainers privately first. From 4e6d40677a53a9434c5c74860927424228b39617 Mon Sep 17 00:00:00 2001 From: Ankit Kotnala Date: Tue, 5 May 2026 20:52:57 +0530 Subject: [PATCH 3/4] Fix pip install command in CONTRIBUTING.md Done with the modifications suggested by the maintainer. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bdce6f7..1d60ee0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,7 +56,7 @@ source .venv/bin/activate Install the project with development dependencies: ```bash -pip install -e ".[dev]" +pip install -e ``` ## Linting and Formatting From 445d9978acf77e527234c0a1e8451cc94617d95a Mon Sep 17 00:00:00 2001 From: Ankit Kotnala Date: Tue, 5 May 2026 20:56:31 +0530 Subject: [PATCH 4/4] Fix pip install command in CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1d60ee0..da58aa0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,7 +56,7 @@ source .venv/bin/activate Install the project with development dependencies: ```bash -pip install -e +pip install -e . ``` ## Linting and Formatting