Metadata-Version: 2.4
Name: humandelta
Version: 0.1.0
Summary: Human Delta dev platform SDK — Knowledge Infrastructure for Agent Applications
Project-URL: Homepage, https://humandelta.ai
Project-URL: Documentation, https://docs.humandelta.ai
Project-URL: Repository, https://github.com/Human-Delta-inc/humandelta-py
Author-email: Human Delta <eng@humandelta.ai>
License: MIT
Keywords: agents,ai,knowledge,memory,rag
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-httpretty; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# humandelta

Python SDK for [Human Delta](https://humandelta.ai) — Knowledge Infrastructure for Agent Applications.

## Install

```bash
pip install humandelta
```

## Quickstart

```python
from humandelta import HumanDelta

hd = HumanDelta(api_key="hd_live_...")

# Crawl a website and wait for it to finish
job = hd.indexes.create("https://support.yoursite.com", max_pages=50)
job.wait()

# Semantic search
results = hd.search("how do I cancel my subscription")
for r in results:
    print(r.score, r.source_url)
    print(r.text[:200])

# Read a file from Memory by path
print(hd.fs.read("/memory/SOURCES.md"))

# List a directory
for entry in hd.fs.list("/source/website"):
    print(entry.path, "DIR" if entry.is_dir else "")

# Upload a PDF or audio file
doc = hd.documents.upload("./manual.pdf", category="support")
print(doc.doc_id)
```

## API reference

### `HumanDelta(api_key, base_url?)`

| Method | Description |
|---|---|
| `hd.search(query, top_k=10)` | Semantic search over all ingested sources |
| `hd.fs.read(path)` | Read a file from Memory |
| `hd.fs.list(path)` | List directory entries |
| `hd.fs.shell(cmd)` | Run a shell command (bash, grep, tree, etc.) |
| `hd.fs.write(path, content)` | Write to `/agent/` or `/me/` (requires `fs:write` scope) |
| `hd.fs.delete(path)` | Delete from `/agent/` or `/me/` (requires `fs:write` scope) |
| `hd.indexes.create(url, max_pages, name)` | Start a website crawl |
| `hd.indexes.get(job_id)` | Fetch a single index job |
| `hd.indexes.list()` | List recent index jobs |
| `hd.documents.upload(file_path, category?, doc_name?)` | Upload PDF, audio, image, or CSV |
| `hd.documents.list(category?)` | List uploaded documents |
| `hd.documents.delete(doc_id)` | Delete a document |

### `IndexJob`

| Method | Description |
|---|---|
| `.wait(interval=3, timeout=600)` | Block until crawl finishes |
| `.refresh()` | Fetch latest status |
| `.cancel()` | Cancel a running job |

## Memory layout

```
/memory/          ← agent hub (README, SOURCES)
/source/website/  ← crawled websites
/source/zendesk2/ ← Zendesk articles
/agent/           ← org-wide writable notes
/me/              ← user-private notes
/uploads/         ← uploaded files (extracted text)
```

## Auth

All requests use `Authorization: Bearer hd_live_...`. Get your key from the Human Delta dashboard or from your hackathon organizer.
