{"owner":"deepset-ai","repo":"haystack","hasSkills":true,"totalSkillsCount":4,"totalTokensCount":2800,"categories":["root-instruction","mcp-config","marketplace","plugin-manifest"],"hasMcp":true,"mcpConfig":{"mcpServers":{"haystack":{"command":"npx","args":["-y","@modelcontextprotocol/server-haystack"]}}},"found":["AGENTS.md",".cursor/mcp.json",".claude-plugin/marketplace.json",".claude-plugin/plugin.json"],"skills":{"AGENTS.md":"# Haystack Guidelines for AI Agents\n\n## Environment\n\nHaystack uses **Hatch** for environment and dependency management.\n\nDo not run `python` or `pip` directly.\n\nBefore running code on this project, you must be able to run `hatch --version` and get a correct output.\n\nIf not, ask the user where Hatch is or if they want to install it. For installation instructions, refer to https://hatch.pypa.io/latest/install/#installation.\n\n### Run scripts with test dependencies\n\nhatch -e test run python SCRIPT.py\n\n### Open a shell with test dependencies\n\nhatch -e test shell\n\n### Install temporary dependencies (for experiments only)\n\nuv pip install PACKAGE\n\n### Delete the environment\n\nhatch env prune\n\n## Tests\n\nTests run via Hatch and support pytest arguments.\n\nPrefer running tests on a specific module or using `-k`, since the full suite is large.\n\n### Run unit tests\n\nhatch run test:unit\n\n### Run integration tests\n\nhatch run test:integration\n\n## Quality Checks\n\n### Type checking with mypy\nhatch run test:types\n\nType checking targets Python 3.12, above the 3.11 floor in `requires-python`, because numpy's stubs use PEP 695 `type` statements that mypy rejects below 3.12. So mypy will not catch code that breaks on 3.11; the unit test matrix runs on 3.11 and covers that.\n\nTo fix type issues, avoid `type: ignore`, casts, or assertions when possible. If they are necessary, explain why.\n\n### Format and lint\nhatch run fmt\n\n## Release Notes\n\nEvery user-facing PR (not docs, not CI) must include a release note:\n\nhatch run release-note SHORT_DESCRIPTION\n\nEdit the generated file in `releasenotes/notes/`. Release notes use reStructuredText formatting; see the [release notes section in CONTRIBUTING.md](CONTRIBUTING.md#release-notes) for details.\n\n## Pull Requests\n\nCommunity contributors can have only one open pull request at a time in this repository. Before opening a PR on the user's behalf, check whether they already have one open (`gh pr list --author @me`); if so, tell them instead of opening another.\n\nIn addition, there are rules inferred from previous code reviews. Follow them like a\nreviewer's note: they encode reasons, not ceremony, so when a rule genuinely does not\nfit the change at hand, say why rather than contorting the code to satisfy it.\n\nAlso see directory-specific guidelines:\n\n- [docs-website/AGENTS.md](docs-website/AGENTS.md)\n- [docs-website/docs/AGENTS.md](docs-website/docs/AGENTS.md)\n- [haystack/hooks/compaction/AGENTS.md](haystack/hooks/compaction/AGENTS.md)\n- [releasenotes/notes/AGENTS.md](releasenotes/notes/AGENTS.md)\n- [test/AGENTS.md](test/AGENTS.md)\n\n## API Design\n\n- Target the 3.0 API: `ToolInvoker`, `AsyncPipeline`, and non-chat generators were removed — let `Agent` own tool calls, use `Pipeline.run()`/`Pipeline.run_async()`, and use ChatGenerators like `OpenAIChatGenerator`\n- Serialize with the Haystack helpers (`component_to_dict`, `default_from_dict`): in `from_dict()` pass only the fields present to `__init__()` so defaults stay centralized, shallow-copy the payload instead of `deepcopy()`, and keep tools/toolsets nested under `data` — preserves wire compatibility and round-trip fidelity\n- Keep public signatures explicit and compatible: optional params keyword-only after `*` and appended rather than inserted, mirrored constructor params spelled out instead of `*args`/`**kwargs`, and chat generators keeping the `run(messages, *, streaming_callback, generation_kwargs, tools)` order — avoids breaking positional callers\n- Create API clients and load models in `warm_up()`, not `__init__`; implement `warm_up()` only for real setup and make it idempotent — keeps components constructible and serializable without credentials or network\n- Implement `run_async` only when there is a real async execution path — `Pipeline.run_async()` already falls back to `asyncio.to_thread(component.run, ...)` when it is missing; where it exists, keep `run_async`/`warm_up_async`/`close_async` genuinely async with separate async state and hooks, and share sync/async logic through private helpers — prevents event-loop blocking and sync/async drift\n- Pass explicit `required_variables` for optional prompt vars — avoids requiring optional inputs\n- Subclass `Toolset` only when inherited collection APIs match — prefer composition or raise `NotImplementedError`\n- Read live Haystack `State` resources via `state.data.get(...)` or `state.data[...]` — avoids deep-copy bugs\n- Prefer existing `haystack/core/pipeline` APIs or inline logic — avoid duplicate or one-off public APIs\n- Reuse splitter chunk metadata in `haystack/components/preprocessors/` — keep traceability fields like `page_number`, `source_id`, `header`, `parent_headers`, and split positions; add new keys only for existing downstream contracts\n\n## Documentation\n\n- Keep inline comments and private-helper docs to what is non-obvious — remove restatements, keep durable caveats and rationale\n- Keep docstrings current with signatures and behavior, in the existing Haystack style: each public `:param` by meaning, default, and constraints; `:returns:` contracts; exceptions in the existing `:raises ValueError:` style; aliases like `ToolsType` reflected — stale docs mislead users and assistants\n- Keep doc examples minimal, runnable, and local: default constructors with required env vars like `OPENAI_API_KEY` noted nearby, only the imports the snippet uses, no restated defaults (name a model only for model-specific behavior), expected output as comments, generally `# >> ...`\n- When behavior, fields, or names change, update every relevant surface in the same PR: `haystack/components/` docstrings and examples, documentation pages, and `experimental` wording, `pydoc` IDs, and generated markdown filenames when promoting features\n- Choose which documentation versions to update: update `docs-website/docs/` by default; also update the latest stable `versioned_docs/version-X.Y/` pages for corrections to stable docs or already-released core integration features.\n\n## Code Style\n\n- Use keyword args for multi-parameter calls — improves readability and prevents mix-ups\n- Keep lint suppressions exact and current — a `# noqa: PLR0915` only while the code needs it\n- Scope diffs to the stated goal and leave them clean: no unrelated refactors or formatting, no stray `print()`, no filename-only header comments, no unused private helpers or redundant branches, no args that only restate callee defaults\n- Use `{placeholder}` logger templates with kwargs — preserves structured logs and avoids eager formatting\n- Prefix internal helpers and module-level constants with `_` and keep private constants local; never name locals after imported functions, decorators, or utilities — clarifies API boundaries and avoids shadowing\n\n## Type System\n\n- Fix types at the source; where a suppression is unavoidable use a coded `# type: ignore[...]` with a nearby why-safe comment, and add `@overload` only for real API variants\n- Resolve callable annotations with `typing.get_type_hints()` — avoids bugs from raw or string `inspect.signature()` annotations\n- Keep union aliases non-redundant and concept-named — include base types only when subclasses inherit\n- Use `T | None`, not `Optional[T]`, in annotations and casts — keeps typing concise\n- Annotate helper params broadly and accurately — `type | types.UnionType` for class-or-PEP-604 inputs, `Any` for arbitrary typing objects\n\n## Imports\n\n- Import via public APIs in the narrowest clear form (keep module imports like `import httpx` when namespaces matter); keep only used imports plus deliberate compatibility re-exports\n- Use top-level absolute `haystack...` imports in `haystack/components/` and `haystack/core/component/*.py` — keeps component dependencies traceable\n- Use `LazyImport` only for optional third-party deps — otherwise import directly\n\n## Config\n\n- Pass `allowed_modules=` or set `HAYSTACK_DESERIALIZATION_ALLOWLIST` for YAML loads — never widen `haystack/core/serialization_security.py` allowlists in library code\n\n## Testing\n\n- Centralize `DocumentStore` tests in `haystack/testing/document_store.py` mixins — use `DocumentStoreBaseTests` as the minimum suite and compose capability mixins into `DocumentStoreBaseExtendedTests`; add explicit integration skips only for unsupported backend features.\n\n## General\n\n- Define package exports in `__init__.py` via `__all__`; avoid `__all__` in implementation modules — keeps public APIs intentional\n- Update `pyproject.toml` for new package APIs — declare deps and minimum versions used\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/deepset-ai/haystack/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/deepset-ai/haystack/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/deepset-ai/haystack/HEAD/.claude-plugin/plugin.json)"},"files":{"AGENTS.md":"# Haystack Guidelines for AI Agents\n\n## Environment\n\nHaystack uses **Hatch** for environment and dependency management.\n\nDo not run `python` or `pip` directly.\n\nBefore running code on this project, you must be able to run `hatch --version` and get a correct output.\n\nIf not, ask the user where Hatch is or if they want to install it. For installation instructions, refer to https://hatch.pypa.io/latest/install/#installation.\n\n### Run scripts with test dependencies\n\nhatch -e test run python SCRIPT.py\n\n### Open a shell with test dependencies\n\nhatch -e test shell\n\n### Install temporary dependencies (for experiments only)\n\nuv pip install PACKAGE\n\n### Delete the environment\n\nhatch env prune\n\n## Tests\n\nTests run via Hatch and support pytest arguments.\n\nPrefer running tests on a specific module or using `-k`, since the full suite is large.\n\n### Run unit tests\n\nhatch run test:unit\n\n### Run integration tests\n\nhatch run test:integration\n\n## Quality Checks\n\n### Type checking with mypy\nhatch run test:types\n\nType checking targets Python 3.12, above the 3.11 floor in `requires-python`, because numpy's stubs use PEP 695 `type` statements that mypy rejects below 3.12. So mypy will not catch code that breaks on 3.11; the unit test matrix runs on 3.11 and covers that.\n\nTo fix type issues, avoid `type: ignore`, casts, or assertions when possible. If they are necessary, explain why.\n\n### Format and lint\nhatch run fmt\n\n## Release Notes\n\nEvery user-facing PR (not docs, not CI) must include a release note:\n\nhatch run release-note SHORT_DESCRIPTION\n\nEdit the generated file in `releasenotes/notes/`. Release notes use reStructuredText formatting; see the [release notes section in CONTRIBUTING.md](CONTRIBUTING.md#release-notes) for details.\n\n## Pull Requests\n\nCommunity contributors can have only one open pull request at a time in this repository. Before opening a PR on the user's behalf, check whether they already have one open (`gh pr list --author @me`); if so, tell them instead of opening another.\n\nIn addition, there are rules inferred from previous code reviews. Follow them like a\nreviewer's note: they encode reasons, not ceremony, so when a rule genuinely does not\nfit the change at hand, say why rather than contorting the code to satisfy it.\n\nAlso see directory-specific guidelines:\n\n- [docs-website/AGENTS.md](docs-website/AGENTS.md)\n- [docs-website/docs/AGENTS.md](docs-website/docs/AGENTS.md)\n- [haystack/hooks/compaction/AGENTS.md](haystack/hooks/compaction/AGENTS.md)\n- [releasenotes/notes/AGENTS.md](releasenotes/notes/AGENTS.md)\n- [test/AGENTS.md](test/AGENTS.md)\n\n## API Design\n\n- Target the 3.0 API: `ToolInvoker`, `AsyncPipeline`, and non-chat generators were removed — let `Agent` own tool calls, use `Pipeline.run()`/`Pipeline.run_async()`, and use ChatGenerators like `OpenAIChatGenerator`\n- Serialize with the Haystack helpers (`component_to_dict`, `default_from_dict`): in `from_dict()` pass only the fields present to `__init__()` so defaults stay centralized, shallow-copy the payload instead of `deepcopy()`, and keep tools/toolsets nested under `data` — preserves wire compatibility and round-trip fidelity\n- Keep public signatures explicit and compatible: optional params keyword-only after `*` and appended rather than inserted, mirrored constructor params spelled out instead of `*args`/`**kwargs`, and chat generators keeping the `run(messages, *, streaming_callback, generation_kwargs, tools)` order — avoids breaking positional callers\n- Create API clients and load models in `warm_up()`, not `__init__`; implement `warm_up()` only for real setup and make it idempotent — keeps components constructible and serializable without credentials or network\n- Implement `run_async` only when there is a real async execution path — `Pipeline.run_async()` already falls back to `asyncio.to_thread(component.run, ...)` when it is missing; where it exists, keep `run_async`/`warm_up_async`/`close_async` genuinely async with separate async state and hooks, and share sync/async logic through private helpers — prevents event-loop blocking and sync/async drift\n- Pass explicit `required_variables` for optional prompt vars — avoids requiring optional inputs\n- Subclass `Toolset` only when inherited collection APIs match — prefer composition or raise `NotImplementedError`\n- Read live Haystack `State` resources via `state.data.get(...)` or `state.data[...]` — avoids deep-copy bugs\n- Prefer existing `haystack/core/pipeline` APIs or inline logic — avoid duplicate or one-off public APIs\n- Reuse splitter chunk metadata in `haystack/components/preprocessors/` — keep traceability fields like `page_number`, `source_id`, `header`, `parent_headers`, and split positions; add new keys only for existing downstream contracts\n\n## Documentation\n\n- Keep inline comments and private-helper docs to what is non-obvious — remove restatements, keep durable caveats and rationale\n- Keep docstrings current with signatures and behavior, in the existing Haystack style: each public `:param` by meaning, default, and constraints; `:returns:` contracts; exceptions in the existing `:raises ValueError:` style; aliases like `ToolsType` reflected — stale docs mislead users and assistants\n- Keep doc examples minimal, runnable, and local: default constructors with required env vars like `OPENAI_API_KEY` noted nearby, only the imports the snippet uses, no restated defaults (name a model only for model-specific behavior), expected output as comments, generally `# >> ...`\n- When behavior, fields, or names change, update every relevant surface in the same PR: `haystack/components/` docstrings and examples, documentation pages, and `experimental` wording, `pydoc` IDs, and generated markdown filenames when promoting features\n- Choose which documentation versions to update: update `docs-website/docs/` by default; also update the latest stable `versioned_docs/version-X.Y/` pages for corrections to stable docs or already-released core integration features.\n\n## Code Style\n\n- Use keyword args for multi-parameter calls — improves readability and prevents mix-ups\n- Keep lint suppressions exact and current — a `# noqa: PLR0915` only while the code needs it\n- Scope diffs to the stated goal and leave them clean: no unrelated refactors or formatting, no stray `print()`, no filename-only header comments, no unused private helpers or redundant branches, no args that only restate callee defaults\n- Use `{placeholder}` logger templates with kwargs — preserves structured logs and avoids eager formatting\n- Prefix internal helpers and module-level constants with `_` and keep private constants local; never name locals after imported functions, decorators, or utilities — clarifies API boundaries and avoids shadowing\n\n## Type System\n\n- Fix types at the source; where a suppression is unavoidable use a coded `# type: ignore[...]` with a nearby why-safe comment, and add `@overload` only for real API variants\n- Resolve callable annotations with `typing.get_type_hints()` — avoids bugs from raw or string `inspect.signature()` annotations\n- Keep union aliases non-redundant and concept-named — include base types only when subclasses inherit\n- Use `T | None`, not `Optional[T]`, in annotations and casts — keeps typing concise\n- Annotate helper params broadly and accurately — `type | types.UnionType` for class-or-PEP-604 inputs, `Any` for arbitrary typing objects\n\n## Imports\n\n- Import via public APIs in the narrowest clear form (keep module imports like `import httpx` when namespaces matter); keep only used imports plus deliberate compatibility re-exports\n- Use top-level absolute `haystack...` imports in `haystack/components/` and `haystack/core/component/*.py` — keeps component dependencies traceable\n- Use `LazyImport` only for optional third-party deps — otherwise import directly\n\n## Config\n\n- Pass `allowed_modules=` or set `HAYSTACK_DESERIALIZATION_ALLOWLIST` for YAML loads — never widen `haystack/core/serialization_security.py` allowlists in library code\n\n## Testing\n\n- Centralize `DocumentStore` tests in `haystack/testing/document_store.py` mixins — use `DocumentStoreBaseTests` as the minimum suite and compose capability mixins into `DocumentStoreBaseExtendedTests`; add explicit integration skips only for unsupported backend features.\n\n## General\n\n- Define package exports in `__init__.py` via `__all__`; avoid `__all__` in implementation modules — keeps public APIs intentional\n- Update `pyproject.toml` for new package APIs — declare deps and minimum versions used\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/deepset-ai/haystack/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/deepset-ai/haystack/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/deepset-ai/haystack/HEAD/.claude-plugin/plugin.json)"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/deepset-ai/haystack/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Haystack Guidelines for AI Agents\n\n## Environment\n\nHaystack uses **Hatch** for environment and dependency management.\n\nDo not run `python` or `pip` directly.\n\nBefore running code on this project, you must be able to run `hatch --version` and get a correct output.\n\nIf not, ask the user where Hatch is or if they want to install it. For installation instructions, refer to https://hatch.pypa.io/latest/install/#installation.\n\n### Run scripts with test dependencies\n\nhatch -e test run python SCRIPT.py\n\n### Open a shell with test dependencies\n\nhatch -e test shell\n\n### Install temporary dependencies (for experiments only)\n\nuv pip install PACKAGE\n\n### Delete the environment\n\nhatch env prune\n\n## Tests\n\nTests run via Hatch and support pytest arguments.\n\nPrefer running tests on a specific module or using `-k`, since the full suite is large.\n\n### Run unit tests\n\nhatch run test:unit\n\n### Run integration tests\n\nhatch run test:integration\n\n## Quality Checks\n\n### Type checking with mypy\nhatch run test:types\n\nType checking targets Python 3.12, above the 3.11 floor in `requires-python`, because numpy's stubs use PEP 695 `type` statements that mypy rejects below 3.12. So mypy will not catch code that breaks on 3.11; the unit test matrix runs on 3.11 and covers that.\n\nTo fix type issues, avoid `type: ignore`, casts, or assertions when possible. If they are necessary, explain why.\n\n### Format and lint\nhatch run fmt\n\n## Release Notes\n\nEvery user-facing PR (not docs, not CI) must include a release note:\n\nhatch run release-note SHORT_DESCRIPTION\n\nEdit the generated file in `releasenotes/notes/`. Release notes use reStructuredText formatting; see the [release notes section in CONTRIBUTING.md](CONTRIBUTING.md#release-notes) for details.\n\n## Pull Requests\n\nCommunity contributors can have only one open pull request at a time in this repository. Before opening a PR on the user's behalf, check whether they already have one open (`gh pr list --author @me`); if so, tell them instead of opening another.\n\nIn addition, there are rules inferred from previous code reviews. Follow them like a\nreviewer's note: they encode reasons, not ceremony, so when a rule genuinely does not\nfit the change at hand, say why rather than contorting the code to satisfy it.\n\nAlso see directory-specific guidelines:\n\n- [docs-website/AGENTS.md](docs-website/AGENTS.md)\n- [docs-website/docs/AGENTS.md](docs-website/docs/AGENTS.md)\n- [haystack/hooks/compaction/AGENTS.md](haystack/hooks/compaction/AGENTS.md)\n- [releasenotes/notes/AGENTS.md](releasenotes/notes/AGENTS.md)\n- [test/AGENTS.md](test/AGENTS.md)\n\n## API Design\n\n- Target the 3.0 API: `ToolInvoker`, `AsyncPipeline`, and non-chat generators were removed — let `Agent` own tool calls, use `Pipeline.run()`/`Pipeline.run_async()`, and use ChatGenerators like `OpenAIChatGenerator`\n- Serialize with the Haystack helpers (`component_to_dict`, `default_from_dict`): in `from_dict()` pass only the fields present to `__init__()` so defaults stay centralized, shallow-copy the payload instead of `deepcopy()`, and keep tools/toolsets nested under `data` — preserves wire compatibility and round-trip fidelity\n- Keep public signatures explicit and compatible: optional params keyword-only after `*` and appended rather than inserted, mirrored constructor params spelled out instead of `*args`/`**kwargs`, and chat generators keeping the `run(messages, *, streaming_callback, generation_kwargs, tools)` order — avoids breaking positional callers\n- Create API clients and load models in `warm_up()`, not `__init__`; implement `warm_up()` only for real setup and make it idempotent — keeps components constructible and serializable without credentials or network\n- Implement `run_async` only when there is a real async execution path — `Pipeline.run_async()` already falls back to `asyncio.to_thread(component.run, ...)` when it is missing; where it exists, keep `run_async`/`warm_up_async`/`close_async` genuinely async with separate async state and hooks, and share sync/async logic through private helpers — prevents event-loop blocking and sync/async drift\n- Pass explicit `required_variables` for optional prompt vars — avoids requiring optional inputs\n- Subclass `Toolset` only when inherited collection APIs match — prefer composition or raise `NotImplementedError`\n- Read live Haystack `State` resources via `state.data.get(...)` or `state.data[...]` — avoids deep-copy bugs\n- Prefer existing `haystack/core/pipeline` APIs or inline logic — avoid duplicate or one-off public APIs\n- Reuse splitter chunk metadata in `haystack/components/preprocessors/` — keep traceability fields like `page_number`, `source_id`, `header`, `parent_headers`, and split positions; add new keys only for existing downstream contracts\n\n## Documentation\n\n- Keep inline comments and private-helper docs to what is non-obvious — remove restatements, keep durable caveats and rationale\n- Keep docstrings current with signatures and behavior, in the existing Haystack style: each public `:param` by meaning, default, and constraints; `:returns:` contracts; exceptions in the existing `:raises ValueError:` style; aliases like `ToolsType` reflected — stale docs mislead users and assistants\n- Keep doc examples minimal, runnable, and local: default constructors with required env vars like `OPENAI_API_KEY` noted nearby, only the imports the snippet uses, no restated defaults (name a model only for model-specific behavior), expected output as comments, generally `# >> ...`\n- When behavior, fields, or names change, update every relevant surface in the same PR: `haystack/components/` docstrings and examples, documentation pages, and `experimental` wording, `pydoc` IDs, and generated markdown filenames when promoting features\n- Choose which documentation versions to update: update `docs-website/docs/` by default; also update the latest stable `versioned_docs/version-X.Y/` pages for corrections to stable docs or already-released core integration features.\n\n## Code Style\n\n- Use keyword args for multi-parameter calls — improves readability and prevents mix-ups\n- Keep lint suppressions exact and current — a `# noqa: PLR0915` only while the code needs it\n- Scope diffs to the stated goal and leave them clean: no unrelated refactors or formatting, no stray `print()`, no filename-only header comments, no unused private helpers or redundant branches, no args that only restate callee defaults\n- Use `{placeholder}` logger templates with kwargs — preserves structured logs and avoids eager formatting\n- Prefix internal helpers and module-level constants with `_` and keep private constants local; never name locals after imported functions, decorators, or utilities — clarifies API boundaries and avoids shadowing\n\n## Type System\n\n- Fix types at the source; where a suppression is unavoidable use a coded `# type: ignore[...]` with a nearby why-safe comment, and add `@overload` only for real API variants\n- Resolve callable annotations with `typing.get_type_hints()` — avoids bugs from raw or string `inspect.signature()` annotations\n- Keep union aliases non-redundant and concept-named — include base types only when subclasses inherit\n- Use `T | None`, not `Optional[T]`, in annotations and casts — keeps typing concise\n- Annotate helper params broadly and accurately — `type | types.UnionType` for class-or-PEP-604 inputs, `Any` for arbitrary typing objects\n\n## Imports\n\n- Import via public APIs in the narrowest clear form (keep module imports like `import httpx` when namespaces matter); keep only used imports plus deliberate compatibility re-exports\n- Use top-level absolute `haystack...` imports in `haystack/components/` and `haystack/core/component/*.py` — keeps component dependencies traceable\n- Use `LazyImport` only for optional third-party deps — otherwise import directly\n\n## Config\n\n- Pass `allowed_modules=` or set `HAYSTACK_DESERIALIZATION_ALLOWLIST` for YAML loads — never widen `haystack/core/serialization_security.py` allowlists in library code\n\n## Testing\n\n- Centralize `DocumentStore` tests in `haystack/testing/document_store.py` mixins — use `DocumentStoreBaseTests` as the minimum suite and compose capability mixins into `DocumentStoreBaseExtendedTests`; add explicit integration skips only for unsupported backend features.\n\n## General\n\n- Define package exports in `__init__.py` via `__all__`; avoid `__all__` in implementation modules — keeps public APIs intentional\n- Update `pyproject.toml` for new package APIs — declare deps and minimum versions used\n","isInternal":false,"tokens":1900,"sizeBytes":8556},{"name":"marketplace.json","path":".claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/deepset-ai/haystack/HEAD/.claude-plugin/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/deepset-ai/haystack/HEAD/.claude-plugin/marketplace.json)","tokens":300,"sizeBytes":198},{"name":"plugin.json","path":".claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/deepset-ai/haystack/HEAD/.claude-plugin/plugin.json","title":"claude-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/deepset-ai/haystack/HEAD/.claude-plugin/plugin.json)","tokens":300,"sizeBytes":184},{"name":"mcp.json","path":".cursor/mcp.json","rawUrl":"https://raw.githubusercontent.com/deepset-ai/haystack/HEAD/.cursor/mcp.json","title":"Model Context Protocol (MCP) Configuration","category":"mcp-config","format":"json","content":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/deepset-ai/haystack/HEAD/.cursor/mcp.json)","tokens":300,"sizeBytes":177}],"systemPromptSnippet":"<yakaai_skills repo=\"deepset-ai/haystack\">\n<!-- File: AGENTS.md (Tokens: ~1900 | Category: root-instruction) -->\n# Haystack Guidelines for AI Agents\n\n## Environment\n\nHaystack uses **Hatch** for environment and dependency management.\n\nDo not run `python` or `pip` directly.\n\nBefore running code on this project, you must be able to run `hatch --version` and get a correct output.\n\nIf not, ask the user where Hatch is or if they want to install it. For installation instructions, refer to https://hatch.pypa.io/latest/install/#installation.\n\n### Run scripts with test dependencies\n\nhatch -e test run python SCRIPT.py\n\n### Open a shell with test dependencies\n\nhatch -e test shell\n\n### Install temporary dependencies (for experiments only)\n\nuv pip install PACKAGE\n\n### Delete the environment\n\nhatch env prune\n\n## Tests\n\nTests run via Hatch and support pytest arguments.\n\nPrefer running tests on a specific module or using `-k`, since the full suite is large.\n\n### Run unit tests\n\nhatch run test:unit\n\n### Run integration tests\n\nhatch run test:integration\n\n## Quality Checks\n\n### Type checking with mypy\nhatch run test:types\n\nType checking targets Python 3.12, above the 3.11 floor in `requires-python`, because numpy's stubs use PEP 695 `type` statements that mypy rejects below 3.12. So mypy will not catch code that breaks on 3.11; the unit test matrix runs on 3.11 and covers that.\n\nTo fix type issues, avoid `type: ignore`, casts, or assertions when possible. If they are necessary, explain why.\n\n### Format and lint\nhatch run fmt\n\n## Release Notes\n\nEvery user-facing PR (not docs, not CI) must include a release note:\n\nhatch run release-note SHORT_DESCRIPTION\n\nEdit the generated file in `releasenotes/notes/`. Release notes use reStructuredText formatting; see the [release notes section in CONTRIBUTING.md](CONTRIBUTING.md#release-notes) for details.\n\n## Pull Requests\n\nCommunity contributors can have only one open pull request at a time in this repository. Before opening a PR on the user's behalf, check whether they already have one open (`gh pr list --author @me`); if so, tell them instead of opening another.\n\nIn addition, there are rules inferred from previous code reviews. Follow them like a\nreviewer's note: they encode reasons, not ceremony, so when a rule genuinely does not\nfit the change at hand, say why rather than contorting the code to satisfy it.\n\nAlso see directory-specific guidelines:\n\n- [docs-website/AGENTS.md](docs-website/AGENTS.md)\n- [docs-website/docs/AGENTS.md](docs-website/docs/AGENTS.md)\n- [haystack/hooks/compaction/AGENTS.md](haystack/hooks/compaction/AGENTS.md)\n- [releasenotes/notes/AGENTS.md](releasenotes/notes/AGENTS.md)\n- [test/AGENTS.md](test/AGENTS.md)\n\n## API Design\n\n- Target the 3.0 API: `ToolInvoker`, `AsyncPipeline`, and non-chat generators were removed — let `Agent` own tool calls, use `Pipeline.run()`/`Pipeline.run_async()`, and use ChatGenerators like `OpenAIChatGenerator`\n- Serialize with the Haystack helpers (`component_to_dict`, `default_from_dict`): in `from_dict()` pass only the fields present to `__init__()` so defaults stay centralized, shallow-copy the payload instead of `deepcopy()`, and keep tools/toolsets nested under `data` — preserves wire compatibility and round-trip fidelity\n- Keep public signatures explicit and compatible: optional params keyword-only after `*` and appended rather than inserted, mirrored constructor params spelled out instead of `*args`/`**kwargs`, and chat generators keeping the `run(messages, *, streaming_callback, generation_kwargs, tools)` order — avoids breaking positional callers\n- Create API clients and load models in `warm_up()`, not `__init__`; implement `warm_up()` only for real setup and make it idempotent — keeps components constructible and serializable without credentials or network\n- Implement `run_async` only when there is a real async execution path — `Pipeline.run_async()` already falls back to `asyncio.to_thread(component.run, ...)` when it is missing; where it exists, keep `run_async`/`warm_up_async`/`close_async` genuinely async with separate async state and hooks, and share sync/async logic through private helpers — prevents event-loop blocking and sync/async drift\n- Pass explicit `required_variables` for optional prompt vars — avoids requiring optional inputs\n- Subclass `Toolset` only when inherited collection APIs match — prefer composition or raise `NotImplementedError`\n- Read live Haystack `State` resources via `state.data.get(...)` or `state.data[...]` — avoids deep-copy bugs\n- Prefer existing `haystack/core/pipeline` APIs or inline logic — avoid duplicate or one-off public APIs\n- Reuse splitter chunk metadata in `haystack/components/preprocessors/` — keep traceability fields like `page_number`, `source_id`, `header`, `parent_headers`, and split positions; add new keys only for existing downstream contracts\n\n## Documentation\n\n- Keep inline comments and private-helper docs to what is non-obvious — remove restatements, keep durable caveats and rationale\n- Keep docstrings current with signatures and behavior, in the existing Haystack style: each public `:param` by meaning, default, and constraints; `:returns:` contracts; exceptions in the existing `:raises ValueError:` style; aliases like `ToolsType` reflected — stale docs mislead users and assistants\n- Keep doc examples minimal, runnable, and local: default constructors with required env vars like `OPENAI_API_KEY` noted nearby, only the imports the snippet uses, no restated defaults (name a model only for model-specific behavior), expected output as comments, generally `# >> ...`\n- When behavior, fields, or names change, update every relevant surface in the same PR: `haystack/components/` docstrings and examples, documentation pages, and `experimental` wording, `pydoc` IDs, and generated markdown filenames when promoting features\n- Choose which documentation versions to update: update `docs-website/docs/` by default; also update the latest stable `versioned_docs/version-X.Y/` pages for corrections to stable docs or already-released core integration features.\n\n## Code Style\n\n- Use keyword args for multi-parameter calls — improves readability and prevents mix-ups\n- Keep lint suppressions exact and current — a `# noqa: PLR0915` only while the code needs it\n- Scope diffs to the stated goal and leave them clean: no unrelated refactors or formatting, no stray `print()`, no filename-only header comments, no unused private helpers or redundant branches, no args that only restate callee defaults\n- Use `{placeholder}` logger templates with kwargs — preserves structured logs and avoids eager formatting\n- Prefix internal helpers and module-level constants with `_` and keep private constants local; never name locals after imported functions, decorators, or utilities — clarifies API boundaries and avoids shadowing\n\n## Type System\n\n- Fix types at the source; where a suppression is unavoidable use a coded `# type: ignore[...]` with a nearby why-safe comment, and add `@overload` only for real API variants\n- Resolve callable annotations with `typing.get_type_hints()` — avoids bugs from raw or string `inspect.signature()` annotations\n- Keep union aliases non-redundant and concept-named — include base types only when subclasses inherit\n- Use `T | None`, not `Optional[T]`, in annotations and casts — keeps typing concise\n- Annotate helper params broadly and accurately — `type | types.UnionType` for class-or-PEP-604 inputs, `Any` for arbitrary typing objects\n\n## Imports\n\n- Import via public APIs in the narrowest clear form (keep module imports like `import httpx` when namespaces matter); keep only used imports plus deliberate compatibility re-exports\n- Use top-level absolute `haystack...` imports in `haystack/components/` and `haystack/core/component/*.py` — keeps component dependencies traceable\n- Use `LazyImport` only for optional third-party deps — otherwise import directly\n\n## Config\n\n- Pass `allowed_modules=` or set `HAYSTACK_DESERIALIZATION_ALLOWLIST` for YAML loads — never widen `haystack/core/serialization_security.py` allowlists in library code\n\n## Testing\n\n- Centralize `DocumentStore` tests in `haystack/testing/document_store.py` mixins — use `DocumentStoreBaseTests` as the minimum suite and compose capability mixins into `DocumentStoreBaseExtendedTests`; add explicit integration skips only for unsupported backend features.\n\n## General\n\n- Define package exports in `__init__.py` via `__all__`; avoid `__all__` in implementation modules — keeps public APIs intentional\n- Update `pyproject.toml` for new package APIs — declare deps and minimum versions used\n\n<!-- File: .claude-plugin/marketplace.json (Tokens: ~300 | Category: marketplace) -->\n# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/deepset-ai/haystack/HEAD/.claude-plugin/marketplace.json)\n\n<!-- File: .claude-plugin/plugin.json (Tokens: ~300 | Category: plugin-manifest) -->\n# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/deepset-ai/haystack/HEAD/.claude-plugin/plugin.json)\n\n<!-- File: .cursor/mcp.json (Tokens: ~300 | Category: mcp-config) -->\n# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/deepset-ai/haystack/HEAD/.cursor/mcp.json)\n</yakaai_skills>"}