Metadata-Version: 2.4
Name: oruk-export
Version: 0.1.0a2
Summary: Customer-run Hume metadata archives, offline inventory verification, and explicit audio preservation
Author: Oruk AI
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Oruk Export — alpha

Customer-run Hume metadata archives, offline verification/copying, and a separate
explicit audio-preservation command. Archives may contain prompts, transcripts
and customer secrets. They are **unencrypted** and belong in customer-controlled
private storage. These tools do not import an account into Oruk or Hume, recreate
a custom voice, infer cloning rights, or prove a complete point-in-time backup.

This source prepares Python `oruk-export` **0.1.0a2** and npm `@oruk/export`
**0.1.0-alpha.2**. The names and install examples are proposed package interfaces,
not proof that Oruk controls the registry names or that either package is
published. Use reviewed local artifacts until a registry delivery is verified.

## Requirements

- macOS or Linux, with POSIX no-follow and private-file operations.
- Python 3.10 or later. The Python runtime has no third-party dependencies.
- The npm wrapper additionally requires Node 18 or later **and an already
  installed Python 3.10+**. It does not install or download Python. It is not a
  standalone JavaScript exporter. Native Windows private-archive support is not
  implemented.

After installing a reviewed local wheel or npm tarball, both packages expose:

```sh
oruk-export --plan
oruk-export --help
oruk-export-audio --help
```

These planning/help commands require no provider key or request. The npm wrapper
looks for `python3` on PATH. If necessary, set `ORUK_EXPORT_PYTHON` to an existing
Python executable path; it is an executable name/path, not a shell command.
The wrapper uses isolated Python startup and the exact Python sources included
in the package. It has no install scripts, runtime downloads or shell
interpolation. It forwards arguments, standard input/output, exit codes and
SIGINT/SIGTERM/SIGHUP cancellation; after five seconds it asks a still-running
direct child to stop with SIGKILL and waits for actual child closure. This is
not a hard kernel deadline or ownership of arbitrary child-created processes.

## Metadata and offline modes

`oruk-export --export --output /absolute/real/parent/new-export` performs the
explicit metadata collection using `HUME_API_KEY` from the environment. Do not
put the key in a command argument. Metadata mode does not reconstruct or download
audio. It collects all-version config/prompt/tool records, groups, chats, events
and custom-voice metadata. A completed-section result is not a stable account
snapshot; changing data, caps or inconsistent pages can produce a partial archive.

```sh
oruk-export --verify /absolute/real/parent/saved-export
oruk-export --restore /absolute/real/parent/saved-export --output /absolute/real/parent/new-copy
```

Verification and restoration are offline. Restoration means an exact private
local copy, not a service import. An independently retained
`--expected-manifest-sha256` can bind the intended inventory. A self-consistent
manifest alone does not establish provider authenticity or latestness. Valid
partial archives remain visibly partial.

## Audio is a separate explicit operation

Use `oruk-export-audio --help` for its exact current options and limits before
any provider operation; this audio version has no `--plan` mode. Hume's audio retrieval endpoint may queue
reconstruction; it is not a read-only metadata operation. Audio reconstruction,
status observation and signed-URL download require the command's explicit
opt-in, source pin and exact host controls. Pending/failed/expired audio remains
an incomplete result. A signed URL is not a durable backup. The API key is not
forwarded to the audio download host.

The audio command also offers offline modes. Both independent pins are required:

```sh
oruk-export-audio --verify /absolute/private/audio-attempt \
  --metadata-archive /absolute/private/metadata-archive \
  --expected-manifest-sha256 <metadata-manifest-sha256> \
  --expected-audio-manifest-sha256 <audio-manifest-sha256>

oruk-export-audio --restore /absolute/private/audio-attempt \
  --metadata-archive /absolute/private/metadata-archive \
  --expected-manifest-sha256 <metadata-manifest-sha256> \
  --expected-audio-manifest-sha256 <audio-manifest-sha256> \
  --output /absolute/private/new-audio-copy
```

These modes read no key, perform no DNS/network requests, and never reconstruct
or resume audio. They check every expected chat and file, then recheck the copied
destination. A valid partial inventory stays partial (exit 2); saved bytes for
every selected chat yield exit 0, including an explicitly empty chat inventory.
Malformed/incomplete publication, missing final manifest or failed verification
returns exit 1. Retain an intent-only crash as unresolved. Restoration copies
only the audio attempt; retain the separately pinned metadata archive too.
Neither hashes nor `saved` disposition validate decoding, provider completeness
or audible content. Earlier a1 artifact tests do not qualify the a2 packages.

Both commands create new private destinations and refuse overwrite/resume of an
existing attempt. Cooperative socket/deadline checks do not guarantee a hard
wall-clock bound. Handle the resulting archive, copied backups and encryption
keys using the customer's own controls. The MIT software license does not grant
rights to export, retain, distribute or clone any customer/provider content.
