Metadata-Version: 2.5
Name: hardcarrx
Version: 0.1.0b1
Summary: Python SDK and CLI for the Hardcarrx API.
Project-URL: Homepage, https://www.hardcarrx.com
Project-URL: Documentation, https://docs.hardcarrx.com/sdk
Project-URL: Repository, https://github.com/Hardcarrx/Hardcarrx-SDK
Project-URL: Issues, https://github.com/Hardcarrx/Hardcarrx-SDK/issues
Author: Hardcarrx
License: MIT
License-File: LICENSE
Keywords: ai,cli,hardcarrx,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: httpx[http2]<1,>=0.27
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: rich<15,>=13
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer<1,>=0.12
Requires-Dist: typing-extensions>=4.9; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: pyyaml==6.0.2; extra == 'dev'
Requires-Dist: ruff==0.12.5; extra == 'dev'
Description-Content-Type: text/markdown

# Hardcarrx Python SDK

Python SDK and CLI for the Hardcarrx API.

Status: private beta. This package is not published to PyPI, and the source
repository is not publicly installable. REST remains the supported public
integration path.

Hardcarrx gives developers one API surface for model routing, provider discovery, workspace memory, and usage visibility.

Canonical SDK handbook: https://docs.hardcarrx.com/sdk

## What You Can Do

- Send chat completions through Hardcarrx routing.
- List available providers and models from the live runtime catalog.
- Use your own provider key per request when needed.
- Write and search workspace memory.
- Inspect usage and subscription state for authenticated workspace sessions.
- Configure workspace Langfuse telemetry export for gateway-side LLM observability.
- Use the `hardcarrx` CLI for quick tests, chatbox sessions, catalog checks, memory operations, and SDK updates.

## Local Development Installation

```bash
cd python
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
```

Verify the CLI:

```bash
hardcarrx version
hardcarrx doctor
```

## 60-Second CLI Quickstart

Create a workspace API key in the Hardcarrx dashboard, then:

```bash
export HARDCARRX_API_KEY=hxv_your_workspace_api_key

hardcarrx providers list
hardcarrx models list --provider openai
hardcarrx chat gpt-4.1-mini "Reply with exactly: hello from hardcarrx" --provider openai
```

Open an interactive chatbox:

```bash
hardcarrx chatbox --provider openai --model gpt-4.1-mini
```

Chatbox commands:

```text
/clear
/provider openrouter
/model openai/gpt-4.1-mini
/help
/exit
```

## Python Quickstart

```python
from hardcarrx import Hardcarrx

client = Hardcarrx(api_key="hxv_your_workspace_api_key")

try:
    response = client.routing.chat(
        provider="openai",
        model="gpt-4.1-mini",
        messages=[
            {"role": "user", "content": "Reply with exactly: hello from hardcarrx"},
        ],
    )
    print(response.choices[0].message.content)
finally:
    client.close()
```

For an environment-driven version, see `../examples/python/quickstart_chat.py`.

## Authentication

Most integrations should use a Hardcarrx workspace API key.

```bash
export HARDCARRX_API_KEY=hxv_your_workspace_api_key
```

API key auth is used for:

- provider catalog
- model catalog
- routing chat completions
- memory write/search
- request-log list/detail

The SDK uses the current workspace names:

- `HARDCARRX_API_KEY`
- `HARDCARRX_WORKSPACE_ID`

Bearer-token auth is reserved for account/workspace session endpoints such as usage and subscription lookup.

```bash
export HARDCARRX_BEARER_TOKEN=your_session_token
export HARDCARRX_WORKSPACE_ID=your_workspace_uuid
hardcarrx usage get
```

### Browser Login Boundary

The source contains an experimental OAuth/PKCE CLI flow for internal testing.
It is not customer-ready, is not part of the private-beta quickstart, and must
not be used unless a dedicated Hardcarrx CLI auth client and callback are
configured and verified. Use workspace API keys for SDK traffic.

## Provider Keys

Hardcarrx supports provider credentials in two ways:

- save provider keys in the dashboard
- pass a provider key per request with `--provider-key`

Example per-request BYOK call:

```bash
export HARDCARRX_API_KEY=hxv_your_workspace_api_key
export HARDCARRX_PROVIDER_KEY=sk_provider_key

hardcarrx chat gpt-4.1-mini \
  "Reply with exactly: provider key works" \
  --provider openai \
  --provider-key "$HARDCARRX_PROVIDER_KEY"
```

Do not commit workspace API keys, provider keys, bearer tokens, or browser-login credentials.

## CLI Reference

### Install And Update

```bash
hardcarrx version
hardcarrx doctor
hardcarrx update
hardcarrx update --dry-run
hardcarrx update --yes
```

`hardcarrx update` shows your installed SDK version and the latest available version, then asks before updating.

### Catalog

```bash
hardcarrx providers list
hardcarrx models list
hardcarrx models list --provider openai
```

### Chat

```bash
hardcarrx chat gpt-4.1-mini "Hello from Hardcarrx" --provider openai
hardcarrx chatbox --provider openai --model gpt-4.1-mini
```

### Memory

```bash
hardcarrx memory write "Customer prefers concise answers" \
  --memory-type fact \
  --scope-type workspace \
  --source-type user_input

hardcarrx memory search "concise answers"
```

With metadata:

```bash
hardcarrx memory write \
  "Save launch preference" \
  --memory-type fact \
  --scope-type workspace \
  --source-type user_input \
  --metadata-json '{"folder":"launch","tag":"preferences"}' \
  --structured-payload-json '{"priority":"high","owner":"team"}'
```

### Usage

```bash
export HARDCARRX_BEARER_TOKEN=your_session_token
export HARDCARRX_WORKSPACE_ID=your_workspace_uuid
hardcarrx usage get
```

### Langfuse Integration

Langfuse export is configured per workspace. HARDCARRX sends gateway-side request, cache, memory, model, latency, and governance telemetry after requests pass through the runtime.

```bash
export HARDCARRX_BEARER_TOKEN=your_session_token
export HARDCARRX_WORKSPACE_ID=your_workspace_uuid

hardcarrx integrations langfuse get
hardcarrx integrations langfuse set \
  --enabled \
  --host https://cloud.langfuse.com \
  --public-key pk-lf-your-public-key \
  --secret-key sk-lf-your-secret-key
```

Python:

```python
from hardcarrx import Hardcarrx

client = Hardcarrx.with_bearer_token(
    "your_session_token",
    workspace_id="your_workspace_uuid",
)

settings = client.integrations.langfuse.get()
print(settings.configured)

client.integrations.langfuse.update(
    enabled=True,
    host="https://cloud.langfuse.com",
    public_key="pk-lf-your-public-key",
    secret_key="sk-lf-your-secret-key",
)
```

## Example Scripts

- `../examples/python/quickstart_chat.py` - environment-driven single-message chat quickstart
- `../examples/python/list_catalog.py` - list providers and models
- `../examples/python/chat_routing.py` - explicit OpenAI and OpenRouter routing examples
- `../examples/python/env.example` - environment variable template

Example:

```bash
cp ../examples/python/env.example .env
python -m pip install -e .
python ../examples/python/quickstart_chat.py "Reply with exactly: quickstart ok"
```

## Environment Variables

| Variable | Purpose |
| --- | --- |
| `HARDCARRX_API_KEY` | Workspace API key for routing, catalog, and memory calls |
| `HARDCARRX_WORKSPACE_ID` | Optional workspace id when an endpoint needs explicit workspace scope |
| `HARDCARRX_PROVIDER` | Provider hint for examples, such as `openai` or `openrouter` |
| `HARDCARRX_MODEL` | Model id for examples, such as `gpt-4.1-mini` |
| `HARDCARRX_PROVIDER_KEY` | Optional per-request BYOK provider key |
| `HARDCARRX_BASE_URL` | Optional API base URL override |
| `HARDCARRX_BEARER_TOKEN` | Session bearer token for account/workspace-style endpoints |
| `HARDCARRX_CONFIG_DIR` | Optional CLI credentials directory override |

## Python SDK Surface

Current live resources:

```python
client.providers.list()
client.models.list()
client.model_directory.get()
client.routing.chat(...)
client.memory.write(...)
client.memory.search(...)
client.logs.list(...)
client.logs.get(...)
client.usage.get(...)
client.integrations.langfuse.get()
client.integrations.langfuse.update(...)
```

Async client support is available for implemented resources where exposed by the package.

## Current Status

This package is an alpha release.

Live and tested:

- provider catalog
- model catalog
- routing chat
- memory write/search
- request-log list/detail
- usage lookup
- Langfuse integration get/update
- CLI chat/chatbox
- CLI Langfuse integration get/set
- CLI update checks

Still evolving:

- streaming response decoding
- pagination helpers
- broader resource coverage
- customer-ready browser-login app configuration

## Development

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
pytest -q
python -m build
```

## Support

- SDK handbook: https://docs.hardcarrx.com/sdk
- API reference: https://docs.hardcarrx.com/api-reference
- Repository: https://github.com/Hardcarrx/Hardcarrx-SDK
- Issues: https://github.com/Hardcarrx/Hardcarrx-SDK/issues
- Security reports: see `SECURITY.md`
- Contributions: see `CONTRIBUTING.md`
- Changelog: `CHANGELOG.md`

## License

MIT
