# Use GH0ST Qwen from your own project

Run the GH0ST model API once, then call it from JavaScript, Python, or any HTTP client. Your project does not need the event-agent runtime or a wallet for this local integration.

The supported model ID is `gh0st-qwen3-1.7b`. The API performs local inference using the pinned Qwen3-1.7B quantized model. GH0ST supplies the runtime and interface; it does not claim to have trained Qwen. Consult the [upstream Qwen model card](https://huggingface.co/Qwen/Qwen3-1.7B) and the [quantized model source](https://huggingface.co/unsloth/Qwen3-1.7B-GGUF) for their respective licensing and attribution. Exact local model and runtime pins are recorded in [LOCAL-MODEL.md](local-model.md).

## 1. Start the model API

From the Agent Kit directory:

```sh
npm install --ignore-scripts --no-audit --no-fund
npm run runtime:setup
npm run model:setup
npm run api
```

The setup commands prepare an isolated Python runtime and download/check the pinned model. They may take time and require a native build toolchain. A developer who already has the pinned runtime and weights can supply their absolute paths:

```sh
GH0ST_QWEN_PYTHON=/absolute/path/to/venv/bin/python \
GH0ST_QWEN_MODEL=/absolute/path/to/Qwen3-1.7B-Q4_K_M.gguf \
  npm run api
```

The model file must match the pinned hash. Renaming a different model does not make it compatible. Wait for `Qwen is ready.` before making a generation request. The service listens on `127.0.0.1:8790`; use `npm run api -- --port 8791` to choose another local port.

You can start the installed source checkout from another directory with:

```sh
npm --prefix /absolute/path/to/agent-kit run api
```

The inference process remains warm between calls. Each request supplies its own complete conversation; the API does not retain chat history for you.

## 2. Make a direct HTTP request

List supported models:

```sh
curl --fail-with-body --silent --show-error \
  http://127.0.0.1:8790/v1/models
```

Generate text:

```sh
curl --fail-with-body --silent --show-error \
  http://127.0.0.1:8790/v1/chat/completions \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "gh0st-qwen3-1.7b",
    "messages": [
      {"role": "system", "content": "Use clear, concise language."},
      {"role": "user", "content": "Welcome a developer building their first community agent."}
    ],
    "max_tokens": 128,
    "temperature": 0.3,
    "stream": false
  }'
```

Read answer text from `choices[0].message.content`. The response also contains `id`, `model`, `choices[0].finish_reason`, actual token `usage`, and a `gh0st` object containing backend and model-hash metadata. `finish_reason: "length"` means the output reached its token limit; it is not a complete-answer guarantee.

## 3. Add the JavaScript client to another project

Install the local checkout as a dependency:

```sh
cd /path/to/your-project
npm install /absolute/path/to/agent-kit
```

To move the client package between machines, create an npm tarball from the Agent Kit checkout and install the resulting `.tgz` in the other project. The package contains client/runtime source, not model weights or a prebuilt native inference environment. Run the setup commands on the machine hosting inference.

```sh
# In the Agent Kit checkout:
npm pack

# In your project; use the exact filename printed by npm pack:
npm install /absolute/path/to/gh0st-agent-kit-0.2.0-alpha.1.tgz
```

Create `example.mjs` in your project:

```js
import { createQwenClient } from '@gh0st/agent-kit/client';

const client = createQwenClient({
  baseURL: 'http://127.0.0.1:8790/v1',
  timeoutMs: 90_000,
});

const result = await client.generate(
  'Welcome a developer building their first community agent.',
  { system: 'Use clear, concise language.', maxTokens: 128, temperature: 0.3 },
);

console.log(result.content);
console.log(result.usage);
console.log(result.gh0st);
```

Run `node example.mjs`. The example prints the actual generated answer and returned metadata. It has no fixture fallback.

For a conversation, use `client.chat({ messages, maxTokens, temperature })`. Pass every message you want the model to see, including previous assistant replies. `client.models()` returns the supported model list. Both generation methods return a normalized object with `content`, `finishReason`, camel-case token counts in `usage`, and `gh0st` metadata. The client also accepts an `AbortSignal` as `signal`; failed calls are not retried automatically.

## 4. Add the Python client

Use Python 3.10 or later. Install the Python package into your own project's environment:

```sh
python3 -m pip install /absolute/path/to/agent-kit/python
```

```python
from gh0st_qwen import GH0STQwen, GH0STError

client = GH0STQwen(base_url="http://127.0.0.1:8790/v1", timeout=90)

try:
    answer = client.generate(
        "Welcome a developer building their first community agent.",
        system="Use clear, concise language.",
        max_tokens=128,
        temperature=0.3,
    )
    print(answer)
except GH0STError as error:
    print(f"Generation failed: {error}")
```

`client.generate(...)` returns the answer string. `client.chat(messages, max_tokens=256, temperature=0.3)` returns the complete HTTP response dictionary, including usage and `gh0st`. `client.models()` reads the model list. See the [Python package guide](python-client.md) for error types and tests. The client uses only Python's standard library at runtime.

## Supported request subset

| Setting | Support |
| --- | --- |
| Model | `gh0st-qwen3-1.7b` |
| Message roles | `system`, `user`, `assistant`, with nonempty text content |
| Output limit | `max_tokens` / Python `max_tokens` / JavaScript `maxTokens`: 1–512 |
| Temperature | 0–1 |
| Streaming | `false` only |
| Images, audio, structured content parts | Unsupported |
| Native tool/function calls and tool-role messages | Unsupported by this HTTP endpoint |

Both clients bound request/response sizes and expose this supported subset. The server remains authoritative for admission and model limits. Model output is untrusted text; your application decides how to display it or act on it.

If `GH0ST_QWEN_API_KEY` is configured on the server, pass the matching key as JavaScript `apiKey`, Python `api_key`, or an HTTP `Authorization: Bearer ...` header. Keep keys in backend configuration rather than public frontend source. The server binds to loopback; the clients require HTTPS for a remote address. Remote hosting, TLS and access control are separate deployment work.

This is a local API integration. Its `gh0st.execution` is `local` and `gh0st.billed` is `false`. Model hashes identify the selected artifact; these fields are not an ICP execution proof or a cryptographic proof that an answer is correct. Production GH0ST-token billing, public capacity guarantees and hosted API access are separate from this local service.