Metadata-Version: 2.4
Name: vaultiq
Version: 0.1.0
Summary: Python SDK for VaultIQ — RAG as a Service
Author: VaultIQ Inc.
Maintainer-email: VaultIQ Support <support@vaultiq.ai>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://vaultiq.ai
Project-URL: Documentation, https://www.vaultiq.ai/developers.html
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: httpx>=0.24.0
Requires-Dist: typer>=0.12.0
Requires-Dist: PyYAML>=5.4
Dynamic: license-file

# VaultIQ Python SDK and CLI

Use the VaultIQ API from Python applications or the `vaultiq` command line.
The package is an HTTP client and does not include the VaultIQ backend.

- [Developer documentation](https://www.vaultiq.ai/developers.html)
- [VaultIQ](https://vaultiq.ai)
- [Support](mailto:support@vaultiq.ai)

## Requirements

- Python 3.10 or newer
- Access to a VaultIQ API server
- A VaultIQ account or a kiosk API key

## Installation

```bash
pip install vaultiq
```

This installs both the Python package and the `vaultiq` command.

For an isolated CLI installation, use `pipx`:

```bash
pipx install vaultiq
vaultiq --help
```

## API URL

The CLI defaults to `https://app.vaultiq.ai`. The Python SDK defaults to
`https://api.vaultiq.ai`.

For a self-hosted or private VaultIQ deployment, set the CLI endpoint explicitly
or pass the deployment's API URL to `VaultIQClient`.

## Command-line quick start

Log in and verify access:

```bash
vaultiq auth login
vaultiq list-vaults
```

For a self-hosted or private deployment:

```bash
vaultiq config set-endpoint --api-url https://your-vaultiq-api.example
```

Create a vault, upload a file, index it, and ask a question:

```bash
vaultiq create-vault --vault my-docs
vaultiq push --vault my-docs --file-path report.pdf
vaultiq run-pipeline --vault my-docs --pipeline-type vault_indexing
vaultiq pipeline-status --vault my-docs --pipeline-type vault_indexing
vaultiq ask --vault my-docs --query "What is the summary?"
```

Run `vaultiq --help` for all commands. Teammate administration is available
under `vaultiq teammate --help` when the authenticated account has permission.

The CLI stores its API URL in `~/.vaultiq/config.yaml` and its access token in
`~/.vaultiq/token`. The token file is created with owner-only permissions.

## Python quick start

```python
import os

from vaultiq import Vault, VaultIQClient


client = VaultIQClient()
client.login(
    os.environ["VAULTIQ_USERNAME"],
    os.environ["VAULTIQ_PASSWORD"],
)

client.create_vault("my-docs")
vault = Vault("my-docs", client)
vault.add_data("report.pdf")
vault.train()
vault.wait_for_train()

result = vault.query("What is the summary?")
print(result.answer)

client.close()
```

Set the values before running the example:

```bash
export VAULTIQ_USERNAME=your-username
export VAULTIQ_PASSWORD=your-password
```

Each `VaultIQClient` owns its own HTTP session and access token, so applications
can use multiple VaultIQ accounts or servers without sharing authentication
state.

## Streaming queries

`ask_stream()` yields answer text as it arrives:

```python
with VaultIQClient(
    max_retries=2,
) as client:
    client.login(
        os.environ["VAULTIQ_USERNAME"],
        os.environ["VAULTIQ_PASSWORD"],
    )

    for chunk in client.ask_stream("my-docs", "What is the summary?"):
        print(chunk, end="", flush=True)
```

Connection failures and `5xx` responses can be retried by setting
`max_retries`. Read timeouts are not retried because doing so could submit a
slow query twice.

## Async client

`AsyncVaultIQClient` provides the same operations with `await` and async
streaming:

```python
import asyncio
import os

from vaultiq import AsyncVaultIQClient


async def main():
    async with AsyncVaultIQClient() as client:
        await client.login(
            os.environ["VAULTIQ_USERNAME"],
            os.environ["VAULTIQ_PASSWORD"],
        )
        result = await client.ask("my-docs", "What is the summary?")
        print(result["answer"])


asyncio.run(main())
```

## Kiosk mode

A kiosk API key is tied to a configured vault and permits queries without a
username and password:

```python
import os

from vaultiq import VaultIQClient


client = VaultIQClient(
    kiosk_key=os.environ["VAULTIQ_KIOSK_API_KEY"],
)

result = client.ask("my-vault", "What is the refund policy?")
print(result["answer"])
client.close()
```

The CLI reads the same key from the environment:

```bash
export VAULTIQ_KIOSK_API_KEY="your-kiosk-api-key"
vaultiq kiosk-ask --vault my-vault --query "What is the refund policy?"
```

The SDK blocks vault, file, pipeline, datasource, and teammate administration
methods when a client is using kiosk mode.

For a WhatsApp teammate, store the WhatsApp credentials in the environment:

```bash
export VAULTIQ_WHATSAPP_API_KEY="your-whatsapp-api-key"
export VAULTIQ_WEBHOOK_SECRET="your-webhook-secret"

vaultiq teammate create "WhatsApp Bot" \
  --channel whatsapp \
  --vaults support \
  --whatsapp-phone "1234567890"
```

The CLI also accepts `--api-key`, `--whatsapp-api-key`, and
`--whatsapp-webhook-secret`. A command-line value overrides its environment
variable.

## Common operations

`VaultIQClient` and `AsyncVaultIQClient` provide methods for:

- Creating, describing, listing, and deleting vaults
- Uploading, listing, downloading, and deleting files
- Starting, checking, and stopping pipelines
- Running normal and streaming queries
- Returning retrieval evidence
- Managing staging directories and datasources
- Managing teammates and guided conversations

See the [developer documentation](https://www.vaultiq.ai/developers.html) for
the full SDK and CLI reference.

## Errors

All SDK errors inherit from `VaultIQError`:

```python
from vaultiq.exceptions import VaultIQError


try:
    client.create_vault("my-docs")
except VaultIQError as error:
    print(error.status_code)
    print(error.detail)
    print(error.body)
    print(error.retryable)
```

Specific exceptions include `AuthError`, `VaultNotFoundError`, `TrainingError`,
`RequestTimeoutError`, and `KioskModeError`.

## Security

- Use HTTPS for every non-local API connection.
- Keep usernames, passwords, access tokens, and kiosk keys out of source code.
- Load credentials from environment variables such as
  `VAULTIQ_KIOSK_API_KEY`, `VAULTIQ_WHATSAPP_API_KEY`, and
  `VAULTIQ_WEBHOOK_SECRET`, or from a secrets manager.
- Do not commit `~/.vaultiq/token` or files containing API credentials.

## License

The VaultIQ SDK and CLI are publicly downloadable proprietary software. Use is
governed by the VaultIQ SDK License Agreement included in `LICENSE.txt`.

For help, contact [support@vaultiq.ai](mailto:support@vaultiq.ai).
