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

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

Verify the CLI:

hardcarrx version
hardcarrx doctor

60-Second CLI Quickstart

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

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:

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

Chatbox commands:

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

Python Quickstart

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.

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.

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:

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

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

hardcarrx providers list
hardcarrx models list
hardcarrx models list --provider openai

Chat

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

Memory

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

hardcarrx memory search "concise answers"

With metadata:

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

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.

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:

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:

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

Environment Variables

Python SDK Surface

Current live resources:

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

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