Metadata-Version: 2.5
Name: xquik-haystack
Version: 0.1.5
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.0.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`.

[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`: tweet text, or an empty string when text is missing
- `Document.meta["endpoint"]`: Xquik endpoint family used by the component
- `Document.meta`: available `id`, `url`, and `created_at` source values
- `Document.meta["author"]`: available author identity and verification data
- `Document.meta`: 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.

## 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.
