### Add and Run Examples

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/CONTRIBUTING.md

Steps to add a new example Python script and make it executable. It demonstrates how to add an example file and then run it using the shebang line for execution.

```Python
# add an example to examples/<your-example>.py

#!/usr/bin/env -S rye run python
…
```

```Shell
$ chmod +x examples/<your-example>.py
# run the example against your api
$ ./examples/<your-example>.py
```

--------------------------------

### Install ZeroEntropy Python SDK

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Installs the ZeroEntropy Python SDK from PyPI using pip. This is the first step to using the SDK in your Python projects.

```Shell
pip install zeroentropy
```

--------------------------------

### Setup Environment with Rye

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/CONTRIBUTING.md

Commands to set up the project environment using Rye. This includes bootstrapping the environment or syncing dependencies manually. It also shows how to activate the virtual environment for direct script execution.

```Shell
$ ./scripts/bootstrap
```

```Shell
$ rye sync --all-features
```

```Shell
# Activate the virtual environment - https://docs.python.org/3/library/venv.html#how-venvs-work
$ source .venv/bin/activate
```

```Shell
# now you can omit the `rye run` prefix
$ python script.py
```

--------------------------------

### Build and Install from Source

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/CONTRIBUTING.md

Commands to build the Python package into distributable wheel files and then install it using pip. This process involves using Rye or Python's build module.

```Shell
$ rye build
# or
$ python -m build
```

```Shell
$ pip install ./path-to-wheel-file.whl
```

--------------------------------

### Install from Git

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/CONTRIBUTING.md

Command to install the ZeroEntropy Python library directly from its Git repository using pip.

```Shell
$ pip install git+ssh://git@github.com/zeroentropy-ai/zeroentropy-python.git
```

--------------------------------

### Setup Environment with Pip

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/CONTRIBUTING.md

Instructions for setting up the project environment using standard pip, without Rye. This involves installing development dependencies from a lock file.

```Shell
$ pip install -r requirements-dev.lock
```

--------------------------------

### Install ZeroEntropy with aiohttp Support

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Installs the ZeroEntropy SDK with the `aiohttp` extra, enabling the use of aiohttp as the asynchronous HTTP backend for potentially improved concurrency performance.

```Shell
pip install --pre zeroentropy[aiohttp]
```

--------------------------------

### Run Mock Server for Tests

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/CONTRIBUTING.md

Command to set up a mock server using Prism, which is required for running most tests against the OpenAPI specification.

```Shell
# you will need npm installed
$ npx prism mock path/to/your/openapi.yml
```

--------------------------------

### Run Tests

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/CONTRIBUTING.md

Command to execute the project's test suite.

```Shell
$ ./scripts/test
```

--------------------------------

### Publish PyPI Manually

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/CONTRIBUTING.md

Instructions for manually releasing a package to PyPI by executing a script with a provided PYPI_TOKEN environment variable.

```Shell
# You can release to package managers by using [the `Publish PyPI` GitHub action]
# If the changes aren't made through the automated pipeline, you may want to make releases manually.
$ bin/publish-pypi
```

--------------------------------

### Get Zeroentropy Python Version

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

This snippet demonstrates how to import the zeroentropy library and print its installed version. This is useful for debugging or verifying that an upgrade has taken effect.

```Python
import zeroentropy
print(zeroentropy.__version__)
```

--------------------------------

### Publish PyPI with GitHub Workflow

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/CONTRIBUTING.md

Information on releasing packages to PyPI using a GitHub Actions workflow. This method requires specific organization or repository secrets to be configured.

```Shell
# This requires a setup organization or repository secret to be set up.
# https://www.github.com/zeroentropy-ai/zeroentropy-python/actions/workflows/publish-pypi.yml
```

--------------------------------

### Lint and Format Code

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/CONTRIBUTING.md

Commands to run linting and formatting checks using Ruff and Black. This includes commands to lint the code and automatically format it to fix Ruff issues.

```Shell
$ ./scripts/lint
```

```Shell
$ ./scripts/format
```

--------------------------------

### Make Undocumented POST Requests with ZeroEntropy (Python)

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Provides an example of making requests to undocumented endpoints using `client.post`. It shows how to specify the response casting and send a request body.

```Python
import httpx

response = client.post(
    "/foo",
    cast_to=httpx.Response,
    body={"my_param": True},
)

print(response.headers.get("x-foo"))
```

--------------------------------

### Get Status

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/api.md

Retrieves the current status of the ZeroEntropy service. This method requires no parameters and returns a StatusGetStatusResponse object.

```python
from zeroentropy.types import StatusGetStatusResponse

# Example usage:
# response: StatusGetStatusResponse = client.status.get_status(**params)
```

--------------------------------

### Handling ZeroEntropy API Errors

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Provides a comprehensive example of how to handle various ZeroEntropy API errors, including connection errors, rate limiting, and general status errors. It demonstrates catching specific exceptions like `APIConnectionError` and `APIStatusError`.

```python
import zeroentropy
from zeroentropy import ZeroEntropy

client = ZeroEntropy()

try:
    client.status.get_status()
except zeroentropy.APIConnectionError as e:
    print("The server could not be reached")
    print(e.__cause__)  # an underlying Exception, likely raised within httpx.
except zeroentropy.RateLimitError as e:
    print("A 429 status code was received; we should back off a bit.")
except zeroentropy.APIStatusError as e:
    print("Another non-200-range status code was received")
    print(e.status_code)
    print(e.response)
```

--------------------------------

### Initialize and Use ZeroEntropy Synchronous Client

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Demonstrates how to initialize the synchronous ZeroEntropy client using an API key from environment variables and add a document to a collection. It shows basic client interaction and printing the response message.

```Python
import os
from zeroentropy import ZeroEntropy

client = ZeroEntropy(
    api_key=os.environ.get("ZEROENTROPY_API_KEY"),  # This is the default and can be omitted
)

response = client.documents.add(
    collection_name="example_collection",
    content={
        "type": "text",
        "text": "Example Content",
    },
    path="my_document.txt",
)
print(response.message)
```

--------------------------------

### Initialize and Use ZeroEntropy Asynchronous Client

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Shows how to initialize and use the asynchronous ZeroEntropy client. It includes setting up an async function to add a document and running it using asyncio. The API key is fetched from environment variables.

```Python
import os
import asyncio
from zeroentropy import AsyncZeroEntropy


client = AsyncZeroEntropy(
    api_key=os.environ.get("ZEROENTROPY_API_KEY"),  # This is the default and can be omitted
)


async def main() -> None:
    response = await client.documents.add(
        collection_name="example_collection",
        content={
            "type": "text",
            "text": "Example Content",
        },
        path="my_document.txt",
    )
    print(response.message)


asyncio.run(main())
```

--------------------------------

### Initialize Async Client with aiohttp Backend

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Demonstrates initializing the asynchronous ZeroEntropy client using `aiohttp` as the HTTP backend. This requires instantiating `DefaultAioHttpClient` and passing it to the client constructor within an async context.

```Python
import os
import asyncio
from zeroentropy import DefaultAioHttpClient
from zeroentropy import AsyncZeroEntropy


async def main() -> None:
    async with AsyncZeroEntropy(
        api_key=os.environ.get("ZEROENTROPY_API_KEY"),  # This is the default and can be omitted
        http_client=DefaultAioHttpClient(),
    ) as client:
        response = await client.documents.add(
            collection_name="example_collection",
            content={
                "type": "text",
                "text": "Example Content",
            },
            path="my_document.txt",
        )
        print(response.message)


asyncio.run(main())
```

--------------------------------

### Enabling Logging

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Shows how to enable logging for the ZeroEntropy SDK by setting the `ZEROENTROPY_LOG` environment variable to 'info' or 'debug' for more verbose output.

```shell
$ export ZEROENTROPY_LOG=info
```

--------------------------------

### Configure ZeroEntropy Client with Custom HTTP Client (Python)

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Demonstrates how to override the default httpx client to customize behavior like proxy support and transports. It shows initialization with custom options and per-request customization.

```Python
import httpx
from zeroentropy import ZeroEntropy, DefaultHttpxClient

client = ZeroEntropy(
    # Or use the `ZEROENTROPY_BASE_URL` env var
    base_url="http://my.test.server.example.com:8083",
    http_client=DefaultHttpxClient(
        proxy="http://my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

client.with_options(http_client=DefaultHttpxClient(...))
```

--------------------------------

### Manage ZeroEntropy HTTP Client Resources with Context Manager (Python)

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Shows how to use a context manager with the ZeroEntropy client to ensure that HTTP connections are properly closed upon exiting the context.

```Python
from zeroentropy import ZeroEntropy

with ZeroEntropy() as client:
  # make requests here
  ...

# HTTP client is now closed
```

--------------------------------

### Accessing Page Data Directly

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Shows how to access data directly from the first page response and retrieve information like the next page cursor. It also demonstrates iterating through documents on the current page.

```python
first_page = await client.documents.get_info_list(
    collection_name="example_collection",
)

print(f"next page cursor: {first_page.path_gt}")  # => "next page cursor: ..."
for document in first_page.documents:
    print(document.id)

# Remove `await` for non-async usage.
```

--------------------------------

### Manual Pagination Control

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Illustrates manual control over fetching pages using methods like `.has_next_page()`, `.next_page_info()`, and `.get_next_page()`. This allows for more granular control over pagination logic.

```python
first_page = await client.documents.get_info_list(
    collection_name="example_collection",
)
if first_page.has_next_page():
    print(f"will fetch next page using these details: {first_page.next_page_info()}")
    next_page = await first_page.get_next_page()
    print(f"number of items we just fetched: {len(next_page.documents)}")

# Remove `await` for non-async usage.
```

--------------------------------

### Configuring Request Timeouts

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Demonstrates how to set request timeouts for the ZeroEntropy client, including global configuration and per-request overrides. It shows setting a specific timeout value and using `httpx.Timeout` for granular control.

```python
from zeroentropy import ZeroEntropy
import httpx

# Configure the default for all requests:
client = ZeroEntropy(
    # 20 seconds (default is 1 minute)
    timeout=20.0,
)

# More granular control:
client = ZeroEntropy(
    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)

# Override per-request:
client.with_options(timeout=5.0).status.get_status()
```

--------------------------------

### Fetch Documents Asynchronously

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Demonstrates how to fetch a list of documents asynchronously from a collection, iterating through pages as needed. It shows the use of `async for` with `client.documents.get_info_list`.

```python
import asyncio
from zeroentropy import AsyncZeroEntropy

client = AsyncZeroEntropy()


async def main() -> None:
    all_documents = []
    # Iterate through items across all pages, issuing requests as needed.
    async for document in client.documents.get_info_list(
        collection_name="example_collection",
    ):
        all_documents.append(document)
    print(all_documents)


asyncio.run(main())
```

--------------------------------

### Perform Queries

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/api.md

Facilitates performing various queries on ZeroEntropy data, such as retrieving top documents, top pages, and top snippets. These methods allow for data exploration and analysis based on specified parameters.

```python
from zeroentropy.types import (
    QueryTopDocumentsResponse,
    QueryTopPagesResponse,
    QueryTopSnippetsResponse,
)

# Example usage for top documents query:
# response: QueryTopDocumentsResponse = client.queries.top_documents(**params)

# Example usage for top pages query:
# response: QueryTopPagesResponse = client.queries.top_pages(**params)

# Example usage for top snippets query:
# response: QueryTopSnippetsResponse = client.queries.top_snippets(**params)
```

--------------------------------

### Access Raw Response Data (Headers) with ZeroEntropy (Python)

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Shows how to access the raw HTTP response, including headers, using the `.with_raw_response` attribute. It also demonstrates parsing the response body and accessing parsed data.

```Python
from zeroentropy import ZeroEntropy

client = ZeroEntropy()
response = client.status.with_raw_response.get_status()
print(response.headers.get('X-My-Header'))

status = response.parse()  # get the object that `status.get_status()` would have returned
print(status.num_documents)
```

--------------------------------

### Stream API Response Body with ZeroEntropy (Python)

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Illustrates how to stream the response body using `.with_streaming_response` for efficient handling of large responses. It requires a context manager and shows how to iterate over response lines.

```Python
with client.status.with_streaming_response.get_status() as response:
    print(response.headers.get("X-My-Header"))

    for line in response.iter_lines():
        print(line)
```

--------------------------------

### Manage Documents

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/api.md

Enables the management of documents within ZeroEntropy, including updating, deleting, adding, and retrieving document information. Various methods cater to different document-related operations, each with its own set of parameters.

```python
from zeroentropy.types import (
    DocumentUpdateResponse,
    DocumentDeleteResponse,
    DocumentAddResponse,
    DocumentGetInfoResponse,
    DocumentGetInfoListResponse,
    DocumentGetPageInfoResponse,
)

# Example usage for updating a document:
# response: DocumentUpdateResponse = client.documents.update(**params)

# Example usage for deleting a document:
# response: DocumentDeleteResponse = client.documents.delete(**params)

# Example usage for adding a document:
# response: DocumentAddResponse = client.documents.add(**params)

# Example usage for getting document info:
# response: DocumentGetInfoResponse = client.documents.get_info(**params)

# Example usage for getting a list of document info:
# response: SyncGetDocumentInfoListCursor[DocumentGetInfoListResponse] = client.documents.get_info_list(**params)

# Example usage for getting page info:
# response: DocumentGetPageInfoResponse = client.documents.get_page_info(**params)
```

--------------------------------

### Manage Collections

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/api.md

Provides methods for managing collections within ZeroEntropy. This includes deleting collections, adding new collections, and retrieving a list of existing collections. Each operation may require specific parameters.

```python
from zeroentropy.types import (
    CollectionDeleteResponse,
    CollectionAddResponse,
    CollectionGetListResponse,
)

# Example usage for deleting a collection:
# response: CollectionDeleteResponse = client.collections.delete(**params)

# Example usage for adding a collection:
# response: CollectionAddResponse = client.collections.add(**params)

# Example usage for getting a list of collections:
# response: CollectionGetListResponse = client.collections.get_list()
```

--------------------------------

### Iterate Through Paginated List Responses

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Illustrates how the ZeroEntropy SDK handles paginated list responses by providing auto-paginating iterators. This allows fetching all items from a list without manual pagination logic.

```Python
from zeroentropy import ZeroEntropy

client = ZeroEntropy()

all_documents = []

```

--------------------------------

### Rerank Method

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/api.md

Demonstrates the usage of the `rerank` method within the `client.models` object. This method is used to perform reranking operations, accepting parameters defined in `ModelRerankParams` and returning a `ModelRerankResponse`.

```Python
client.models.rerank(**params) -> ModelRerankResponse
```

--------------------------------

### Configuring Max Retries

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Explains how to configure the maximum number of retries for API requests, either globally for the client or on a per-request basis. It shows setting `max_retries` to 0 to disable retries.

```python
from zeroentropy import ZeroEntropy

# Configure the default for all requests:
client = ZeroEntropy(
    # default is 2
    max_retries=0,
)

# Or, configure per-request:
client.with_options(max_retries=5).status.get_status()
```

--------------------------------

### Check for Null vs. Missing Fields in API Responses (Python)

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/README.md

Demonstrates how to distinguish between a field explicitly set to null and a field that is missing entirely in an API response using the `.model_fields_set` attribute.

```Python
if response.my_field is None:
  if 'my_field' not in response.model_fields_set:
    print('Got json like {}, without a "my_field" key present at all.')
  else:
    print('Got json like {"my_field": null}.')
```

--------------------------------

### Import ModelRerankResponse Type

Source: https://github.com/zeroentropy-ai/zeroentropy-python/blob/main/api.md

Imports the `ModelRerankResponse` type from the `zeroentropy.types` module. This type is used for defining the response structure of reranking operations.

```Python
from zeroentropy.types import ModelRerankResponse
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.