From 53d72fb7384096060c1b44839ff11013ba53cb49 Mon Sep 17 00:00:00 2001 From: Abhinaysai Kamineni <66816045+askmy-stack@users.noreply.github.com> Date: Sun, 2 Aug 2026 15:04:16 -0400 Subject: [PATCH] Add CONTRIBUTING.md and CODE_OF_CONDUCT.md for OSS onboarding. Document local dev (make demo, env vars, tests) and adopt Contributor Covenant 2.1; link both from README alongside SECURITY.md. Co-authored-by: Cursor --- CODE_OF_CONDUCT.md | 133 +++++++++++++++++++++++++++++ CONTRIBUTING.md | 206 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 6 ++ 3 files changed, 345 insertions(+) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..8c2f1b5 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,133 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +**kamineniabhinaysai@gmail.com**. + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact:** Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence:** A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact:** A violation through a single incident or series of +actions. + +**Consequence:** A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact:** A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence:** A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact:** Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence:** A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][mozilla]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][faq]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[mozilla]: https://github.com/mozilla/diversity +[faq]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..75b06c6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,206 @@ +# Contributing to Cortex + +Thank you for helping make Cortex the organizational memory layer for AI-native +teams. This guide covers local development, environment configuration, and how +to submit changes. + +## Before You Start + +- Read the [README](README.md) for product context and architecture. +- Follow our [Code of Conduct](CODE_OF_CONDUCT.md). +- For security issues, see [SECURITY.md](SECURITY.md) — do **not** open public + issues for vulnerabilities. + +## Prerequisites + +| Tool | Version | Purpose | +|------|---------|---------| +| **Docker** | Recent desktop or engine | Kafka, Neo4j, Redis, Postgres, demo stack | +| **Python** | 3.11+ | API, pipeline worker, tests | +| **uv** | Latest | Dependency install and test runner (recommended) | +| **Node.js** | 20+ | MCP server (`mcp/`) and dashboard (`frontend/`) | + +Optional for full pipeline verification: + +- **Ollama** — local LLM extraction when `EXTRACTION_BACKEND=ollama` +- **OpenAI API key** — when using `EXTRACTION_BACKEND=openai` or CMVK with OpenAI + +## Local Development + +### Fastest path — full demo stack + +From the repo root, with Docker running: + +```bash +git clone https://github.com/askmy-stack/cortex +cd cortex +cp .env.example .env # optional; compose defaults work for local demo +make demo # infra + migrations + seed + API + worker + dashboard +open http://localhost:3000 +``` + +On the dashboard, open **Ask**, use workspace `local-dev`, and try: +*Why CockroachDB for payments?* + +`make demo` runs `scripts/demo.sh`, which brings up services, applies Neo4j +migrations, seeds demo decisions, starts the API and pipeline worker, and +runs a sample `POST /query` smoke check. + +### Manual setup + +```bash +# Core infra only (Kafka, Neo4j, Redis, Postgres) +docker compose up -d + +# API + pipeline worker + dashboard (production-like via Docker) +docker compose --profile api --profile frontend up -d --build + +# Connect Slack (optional — requires tokens in .env) +python scripts/connect_slack.py --workspace your-workspace +``` + +**UI development (hot reload):** + +```bash +cd frontend && npm run dev # http://localhost:5173 +``` + +The Docker dashboard is served on port **3000**. Rebuild the frontend image +after UI changes, or use the Vite dev server on **5173** during active work. + +### Python API without Docker profiles + +With infra running and `.env` configured: + +```bash +uv pip install -e ".[dev]" +uv run uvicorn api.main:app --reload --host 0.0.0.0 --port 8000 +``` + +### MCP server + +```bash +cd mcp && npm install && npm test +node server.js # expects CORTEX_API_URL=http://localhost:8000 +``` + +See the MCP block in [README.md](README.md#quickstart) for Claude/Cursor config. + +## Environment Variables + +Copy `.env.example` to `.env` and adjust as needed. Never commit `.env`. + +| Area | Key variables | Notes | +|------|---------------|-------| +| **Neo4j** | `NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD` | Default `bolt://localhost:7687` for host-local uvicorn | +| **Kafka** | `KAFKA_BOOTSTRAP_SERVERS` | `localhost:9092` on host; compose uses internal `kafka:29092` | +| **Redis / Postgres** | `REDIS_*`, `POSTGRES_*`, `TIMESCALE_*` | Compose overrides hostnames inside containers | +| **LLM extraction** | `EXTRACTION_BACKEND`, `OPENAI_API_KEY`, `OLLAMA_*` | `ollama` for local dev; `openai` for production-like runs | +| **API auth** | `CORTEX_API_KEYS`, `CORTEX_DEMO_API_KEY` | Unset = open dev mode; set for staging/production | +| **CMVK** | `CORTEX_CMVK_BACKEND`, `CORTEX_CMVK_ENABLED` | Default `heuristic` needs no LLM; worker fails fast if misconfigured | +| **Connectors** | `SLACK_*`, `GITHUB_*`, `JIRA_*`, `LINEAR_*` | Optional; required only when testing real webhooks | +| **MCP** | `CORTEX_API_URL`, `CORTEX_API_KEY` | `CORTEX_API_KEY` required when `ENVIRONMENT=production` | + +Full comments and defaults live in [`.env.example`](.env.example). + +## Running Tests + +### Python (matches CI) + +```bash +make test # uv run pytest tests/ +make ci # pytest + seed_demo dry-run (same as CI test job) +``` + +Or without Make: + +```bash +uv pip install -e ".[dev]" +CORTEX_CONTRADICTION_ENABLED=false pytest tests/ +python scripts/seed_demo.py --dry-run +python scripts/staging_smoke.py --dry-run +``` + +Most unit tests do not require Docker. Integration tests that need Neo4j or +Kafka are skipped or gated when services are unavailable. + +### Frontend + +```bash +cd frontend +npm ci +npm test +npm run build +npm run test:e2e # Playwright; installs Chromium on first run +``` + +### MCP + +```bash +cd mcp && npm test +``` + +CI runs all of the above on every pull request — see +[`.github/workflows/ci.yml`](.github/workflows/ci.yml). + +## Makefile Targets + +| Target | Description | +|--------|-------------| +| `make demo` | Full local demo stack + smoke query | +| `make demo-dry-run` | Verify seed script without Neo4j | +| `make test` | Run Python test suite | +| `make ci` | Local CI parity (tests + dry-run seed) | +| `make stack` | Start API profile Docker stack | +| `make init-kafka` | Pre-create Kafka topics | +| `make pipeline-restart` | Restart pipeline worker after Python changes | +| `make verify-connectors` | End-to-end connector pipeline checks | + +## Project Layout + +``` +cortex/ +├── api/ FastAPI application +├── pipeline/ Kafka extraction worker +├── mcp/ MCP server (TypeScript) +├── frontend/ React dashboard +├── sdk/ Python client +├── tests/ Pytest suite +├── scripts/ Demo, seed, verification utilities +└── docs/ Deploy guides, ADRs, demo recording +``` + +Deeper architecture notes: [ARCHITECTURE.md](ARCHITECTURE.md), +[docs/DEPLOY.md](docs/DEPLOY.md), [docs/DEPLOY-FREE.md](docs/DEPLOY-FREE.md). + +## Submitting Changes + +1. **Open an issue** (or comment on an existing one) before large changes so + we can align on approach. +2. **Fork and branch** from `main` with a descriptive name, e.g. + `fix/query-cache-invalidation` or `docs/connector-validation`. +3. **Keep PRs focused** — one logical change per pull request when possible. +4. **Run tests locally** — at minimum `make ci` for Python-only changes; + include frontend/MCP tests when you touch those areas. +5. **Update docs** when behavior, env vars, or setup steps change. +6. **Write clear commit messages** — explain *why*, not just *what*. + +Pull requests should describe the problem, the solution, and how you verified +it (commands run, screenshots for UI changes). + +## Code Style + +- **Python:** follow existing patterns in the module you edit; type hints and + pydantic models where the codebase already uses them. +- **TypeScript:** match `mcp/` and `frontend/` conventions; run linters/tests + before pushing. +- **Cypher / SQL migrations:** add numbered files under `graph/migrations/`; + never mutate applied migration history. + +## Questions + +- **Bugs and features:** [GitHub Issues](https://github.com/askmy-stack/cortex/issues) +- **Security:** [SECURITY.md](SECURITY.md) +- **Conduct:** [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) + +We appreciate every contribution — from typo fixes to new connectors. diff --git a/README.md b/README.md index 3ccfbf9..a23858d 100644 --- a/README.md +++ b/README.md @@ -422,6 +422,12 @@ Built on: --- +## Contributing + +We welcome issues and pull requests. See [CONTRIBUTING.md](CONTRIBUTING.md) for +local setup (`make demo`), environment variables, and tests. Please follow our +[Code of Conduct](CODE_OF_CONDUCT.md). Security reports: [SECURITY.md](SECURITY.md). + ## License Apache 2.0 — use it, fork it, build on it.