{"owner":"onyx-dot-app","repo":"onyx","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"files":{"AGENTS.md":"# PROJECT KNOWLEDGE BASE\n\nThis file provides guidance to AI agents when working with code in this repository.\n\n## KEY NOTES\n\n- Python deps live in a `uv`-managed virtualenv at `.venv` (repo root). If it doesn't exist yet, create it\n  with `uv sync --frozen`, then `source .venv/bin/activate`.\n- Test secrets (API keys etc.) are resolved by `backend/tests/utils/aws_secrets.py`, in order: process\n  env vars → the gitignored `.vscode/.env` (also used by the pytest commands in `backend/AGENTS.md`;\n  create it by copying `.vscode/env_template.txt`) → AWS Secrets Manager (requires `aws sso login`).\n  Tests declare what they need via `@pytest.mark.secrets(TestSecret.X)`. If a key you need still can't\n  be resolved, ask the user rather than skipping tests.\n- If using `playwright` to explore the frontend, log in with username `admin_user@example.com` and password\n  `TestPassword123!` (the admin user created by the playwright global setup — see\n  `web/tests/e2e/constants.ts`). If it doesn't exist yet, register it via the signup page; the first user\n  registered automatically becomes admin. The app can be accessed at `http://localhost:3000`.\n- You should assume that all Onyx services are running. To verify, you can check the `backend/log` directory to\n  make sure we see logs coming out from the relevant service.\n- To connect to the Postgres database, use:\n  `PGPASSWORD=\"${POSTGRES_PASSWORD:-password}\" psql -h \"${POSTGRES_HOST:-localhost}\" -U postgres -c \"<SQL>\"`.\n  This works on a host checkout and inside the devcontainer. If no `psql` client is available, fall back to\n  `docker exec onyx-relational_db-1 psql -U postgres -c \"<SQL>\"` (no `-it` — agent shells have no TTY).\n- When making calls to the backend, always go through the frontend. E.g. make a call to `http://localhost:3000/api/persona` not `http://localhost:8080/api/persona`\n\n## Project Overview\n\n**Onyx** (formerly Danswer) is an open-source Gen-AI and Enterprise Search platform that connects to company documents, apps, and people. It features a modular architecture with both Community Edition (MIT licensed) and Enterprise Edition offerings.\n\n### Technology Stack\n\n- **Backend**: Python 3.13, FastAPI, SQLAlchemy, Alembic, Celery\n- **Frontend**: Next.js 16, React 19, TypeScript, Tailwind CSS\n- **Database**: PostgreSQL with Redis caching\n- **Search**: OpenSearch-backed keyword and vector document index\n- **Auth**: OAuth2, SAML, multi-provider support\n- **AI/ML**: LangChain, LiteLLM, multiple embedding models\n\n### Repository Layout & Sub-project Guides\n\nEach sub-project has its own agents file with the standards for that area — read it before working\nthere:\n\n- `backend/` — FastAPI app + Celery workers. `onyx/` is the Community Edition core, `ee/` mirrors its\n  layout for Enterprise features, `alembic/` holds migrations, `tests/` the test suites. Standards\n  (Celery, migrations, testing, error handling, LLM tracing): `backend/AGENTS.md`.\n- `web/` — Next.js frontend. Standards (also cover `desktop/`, the Tauri shell): `web/AGENTS.md`.\n- `mobile/` — React Native + Expo app. Standards: `mobile/AGENTS.md`. Mobile differs from web on\n  several points (no DOM, NativeWind, expo-router), so do **not** assume the web rules apply there.\n\nExplore the tree with `ls` rather than relying on docs for the full package list.\n\n## Code Quality\n\n```bash\n# Install and run pre-commit hooks\npre-commit install\npre-commit run --all-files\n\n# Faster: run only on the files you touched\npre-commit run --files <path> [<path> ...]\n```\n\nNOTE: Always make sure everything is strictly typed (both in Python and Typescript).\n\nNOTE: Keep code comments brief and focused on information that stays relevant long-term.\n\n## Writing\n\nThese rules apply to all prose you write: docs, commit messages, PR descriptions, reports, and replies.\n\nFollow ASD-STE100 Simplified Technical English for technical text:\n\n- Use approved words only. Each word has one meaning.\n- Use one word for one idea. Do not use two words for the same thing.\n- Write short sentences. Use 20 words or less for instructions.\n- Use active voice. Write \"Turn the switch\", not \"The switch must be turned\".\n- Write short paragraphs. Keep one topic in each paragraph.\n- Keep code comments focused on information that is relevant long-term or for future readers.\n\n## Testing\n\nThere are 4 main types of tests: unit, external dependency unit, integration, and playwright e2e\n(`web/tests/e2e`). Commands and guidance for all four live in `backend/AGENTS.md`; shared fixtures\nand deeper detail in `backend/tests/README.md`. Prefer integration tests over the other types.\n\n## Logs\n\nWhen (1) writing integration tests or (2) doing live tests (e.g. curl / playwright) you can get access\nto logs via the `backend/log/<service_name>_debug.log` file. All Onyx services (api_server, web_server, celery_X)\nwill be tailing their logs to this file.\n\n## Security Considerations\n\n- Never commit API keys or secrets to the repository\n- Use the encrypted credential storage for connector credentials\n- Follow existing RBAC patterns for new features\n\n## Creating a Plan\n\nWhen creating a plan in the `plans` directory (gitignored — create it if it doesn't exist), make sure to\ninclude at least these elements:\n\n**Issues to Address**\nWhat the change is meant to do.\n\n**Important Notes**\nThings you come across in your research that are important to the implementation.\n\n**Implementation strategy**\nHow you are going to make the changes happen. High level approach.\n\n**Tests**\nWhat unit (use rarely), external dependency unit, integration, and playwright tests you plan to write to\nverify the correct behavior. Don't overtest. Usually, a given change only needs one type of test.\n\nDo NOT include these: _Timeline_, _Rollback plan_\n\nThis is a minimal list - feel free to include more. Do NOT write code as part of your plan.\nKeep it high level. You can reference certain files or functions though.\n\nBefore writing your plan, make sure to do research. Explore the relevant sections in the codebase.\n\n## Best Practices\n\nIn addition to the other content in this file, best practices for contributing\nto the codebase can be found in the \"Engineering Best Practices\" section of\n`CONTRIBUTING.md`. Understand its contents and follow them.\n"}}