Metadata-Version: 2.4
Name: xquik-haystack
Version: 0.1.3
Summary: Haystack web search components for Xquik public X data. 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,retrieval,social-media,twitter,websearch,x,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
Description-Content-Type: text/markdown

# Retrieve X/Twitter context with Haystack

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

Haystack web search components for retrieving public X/Twitter context through the Xquik REST API.

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

This package is maintained by Xquik as a standalone Haystack integration. It follows the `haystack_integrations` namespace convention and exposes read-only components under:

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

## Available components

- `XquikTweetSearch`: calls `GET /x/tweets/search` and returns matching posts as Haystack `Document` objects.
- `XquikUserTweetsFetcher`: calls `GET /x/users/{id}/tweets` and returns recent public posts for a user as Haystack `Document` objects.

Both components:

- read the API key from `XQUIK_API_KEY` by default
- accept `haystack.utils.Secret` for explicit API key injection
- send the `x-api-key` and `xquik-api-contract: 2026-04-29` headers
- keep `base_url` configurable for tests and controlled deployments
- return `documents`, `links`, `has_more`, and `next_cursor`

## Install

Install from PyPI:

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

## Search public X data

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

- `Document.content`: tweet text, or an empty string when text is missing
- `Document.meta["endpoint"]`: Xquik endpoint family used by the component
- `Document.meta["id"]`: tweet ID when present
- `Document.meta["url"]`: tweet URL when present
- `Document.meta["created_at"]`: tweet creation time when present
- `Document.meta["author"]`: author ID, username, display name, and verification status when present
- `Document.meta` also includes available public metrics such as like, repost, reply, quote, view, and bookmark counts

## Development

This project uses [Hatch](https://hatch.pypa.io/) for build and environment management.

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

Unit tests mock all Xquik HTTP calls. Integration tests can be added later behind an `XQUIK_API_KEY` check.

## Publishing

The release workflow publishes to PyPI with trusted publishing when a GitHub release is published.

Haystack merged the [Xquik integration-directory listing](https://github.com/deepset-ai/haystack-integrations/pull/499).

## License

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