Metadata-Version: 2.5
Name: xquik-haystack
Version: 0.1.7
Summary: Haystack RAG components for Twitter search and public user timelines. Not affiliated with X Corp.
Project-URL: Documentation, https://docs.xquik.com/guides/haystack
Project-URL: Issues, https://github.com/Xquik-dev/xquik-haystack/issues
Project-URL: Source, https://github.com/Xquik-dev/xquik-haystack
Author-email: Xquik <support@xquik.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: haystack,rag,twitter,twitter-api-alternative,twitter-search,user-timeline,xquik
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: haystack-ai==3.3.0
Description-Content-Type: text/markdown

# Twitter search & user timeline components for Haystack

[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13741/badge)](https://www.bestpractices.dev/projects/13741)

Search Twitter and fetch public user timelines in Haystack RAG pipelines.
Each Xquik result becomes a Haystack `Document`.

Xquik is the world's fastest and cheapest X Twitter scraper service with the most complete X data.
Xquik charges only for delivered, unique, filter-matching results and never pads rows.

[Read the Xquik Haystack guide](https://docs.xquik.com/guides/haystack).

## Components

| Task | Haystack Component | Xquik Route | Output |
| --- | --- | --- | --- |
| Search tweets for RAG | `XquikTweetSearch` | `GET /x/tweets/search` | Matching posts as `Document` objects |
| Retrieve a user's timeline | `XquikUserTweetsFetcher` | `GET /x/users/{id}/tweets` | Recent user posts as `Document` objects |

Import both read-only components from the Haystack integration namespace.

```python
from haystack_integrations.components.websearch.xquik import XquikTweetSearch, XquikUserTweetsFetcher
```

Both components read `XQUIK_API_KEY` by default and accept a Haystack `Secret`.
They send `x-api-key` and `xquik-api-contract: 2026-04-29` headers.
Set `base_url` for another Xquik-compatible endpoint. Results include `documents`, `links`,
`has_more`, and `next_cursor`.

Use an [Xquik SDK](https://docs.xquik.com/sdks) for follower exports or posting.

## Install

```bash
pip install xquik-haystack
```

## Build a Haystack RAG pipeline with Twitter search

### Search posts

```python
from haystack import Pipeline
from haystack.utils import Secret
from haystack_integrations.components.websearch.xquik import XquikTweetSearch

search = XquikTweetSearch(api_key=Secret.from_env_var("XQUIK_API_KEY"), top_k=10)

pipeline = Pipeline()
pipeline.add_component("x_search", search)

result = pipeline.run({"x_search": {"query": "haystack ai"}})
documents = result["x_search"]["documents"]
```

### Fetch user posts

```python
from haystack.utils import Secret
from haystack_integrations.components.websearch.xquik import XquikUserTweetsFetcher

fetcher = XquikUserTweetsFetcher(api_key=Secret.from_env_var("XQUIK_API_KEY"))

result = fetcher.run(user_id="example_user", include_replies=False)
documents = result["documents"]
```

## Document mapping

Each tweet becomes a Haystack `Document` with this mapping.

- `Document.content` holds the tweet text, or an empty string when text is
  missing.
- `Document.meta["endpoint"]` names the Xquik endpoint family the component
  used.
- `Document.meta` holds the available `id`, `url`, and `created_at` source
  values.
- `Document.meta["author"]` holds the available author identity and
  verification data.
- `Document.meta` holds the available like, repost, reply, quote, view &
  bookmark counts.

## Development

Use [Hatch](https://hatch.pypa.io/) for builds and environment management.

```bash
pip install hatch==1.18.0
hatch run fmt-check
hatch run test:unit
hatch build
```

Unit tests mock all Xquik HTTP calls.

Run `bin/check-local` before you open a pull request. It runs the lint, license, test & CodeQL checks.

Maintainers release with `bin/release-local <version>` on a clean `main`. It runs the checks, builds, uploads to PyPI, tags the commit and creates the GitHub release. `bin/release-local --dry-run <version>` uploads, tags and releases nothing.

PyPI has no trusted publisher for `xquik-haystack`. A maintainer's PyPI token is the only way it publishes. `bin/release-local` reads it from the Keychain item that `PYPI_KEYCHAIN_SERVICE` names.

## Support & project policies

- [Organization support policy](https://github.com/Xquik-dev/.github/blob/main/SUPPORT.md)
- [Organization security policy](https://github.com/Xquik-dev/.github/blob/main/SECURITY.md)
- [Contribution guide](https://github.com/Xquik-dev/.github/blob/main/CONTRIBUTING.md)

## License

`xquik-haystack` is distributed under the terms of the [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) license.

Xquik is an independent third-party service. Not affiliated with X Corp. "Twitter" and "X" are trademarks of X Corp.
