Metadata-Version: 2.4
Name: hx-sdk
Version: 0.1.0
Summary: HexelStudio Python SDK
Project-URL: Homepage, https://hexelstudio.com
Project-URL: Documentation, https://docs.hexelstudio.com/sdk/python
Project-URL: Repository, https://github.com/hexelstudio/hx-python
Author-email: HexelStudio <support@hexelstudio.com>
License-Expression: MIT
Keywords: ai,hexelstudio,hx,knowledge,memory,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: responses>=0.23.0; extra == 'dev'
Description-Content-Type: text/markdown

# HX SDK - HexelStudio Python SDK

```bash
pip install hx-sdk
```

## Configuration

```bash
export HX_API_KEY="your-api-key"
export HX_ORG_ID="org_xxx"
export HX_WORKSPACE_ID="ws_xxx"
export HX_ENV_ID="env_xxx"
```

Or pass directly:

```python
from hx import Client

client = Client(
    api_key="your-api-key",
    org_id="org_xxx",
    workspace_id="ws_xxx",
    environment_id="env_xxx"
)
```

## Usage

```python
from hx import Client

client = Client()

# Knowledge Store - Search
results = client.knowledge.search("ks_support", "refund policy", top_k=5)

for result in results["results"]:
    print(f"Score: {result['score']:.2f} - {result['text'][:100]}...")

# Memory Store - Add memories from conversation
client.memory.add(
    "ms_support",
    messages=[
        {"role": "user", "content": "I prefer email communication"},
        {"role": "assistant", "content": "Noted, I'll use email for updates"}
    ],
    user_id="user_123"
)

# Memory Store - Search memories
memories = client.memory.search(
    "ms_support",
    "communication preferences",
    user_id="user_123"
)
```

## Services

### Knowledge (`client.knowledge`)

| Method | Description |
|--------|-------------|
| `search(store_id, query, *, top_k=10, score_threshold=None, metadata_filter=None)` | Semantic search |

### Memory (`client.memory`)

| Method | Description |
|--------|-------------|
| `add(store_id, messages, *, user_id, agent_id, run_id, metadata)` | Add memories from messages |
| `search(store_id, query, *, user_id, agent_id, run_id, filters, top_k)` | Search memories |
| `get(store_id, memory_id)` | Get single memory |
| `list(store_id, *, user_id, agent_id, run_id)` | List memories |
| `update(store_id, memory_id, data, *, metadata)` | Update memory |
| `delete(store_id, memory_id)` | Delete memory |
| `delete_all(store_id, *, user_id, agent_id, run_id)` | Bulk delete |
| `history(store_id, memory_id)` | Get change history |
| `reset(store_id)` | Reset all memories |

## Project Structure

```
hx/
├── __init__.py          # Package exports
├── client.py            # Client entry point
├── exceptions.py        # Custom exceptions
├── core/                # Shared SDK infrastructure
│   ├── auth.py          # Token management
│   ├── config.py        # Configuration
│   ├── http.py          # HTTP client
│   └── base.py          # Base client class
└── services/            # Service clients
    ├── memory/
    │   ├── client.py
    │   └── types.py
    └── knowledge/
        ├── client.py
        └── types.py
```

## Adding New Services

1. Create `hx/services/<service_name>/`
2. Add `client.py` extending `BaseClient`
3. Add `types.py` with TypedDicts
4. Register in `Client._init_services()`
