279 lines
7.5 KiB
Markdown
279 lines
7.5 KiB
Markdown
# Getting Started
|
|
|
|
## Overview
|
|
|
|
NOMYO.js provides end-to-end encryption for all communication between your application and NOMYO inference endpoints. Your prompts and responses are encrypted before leaving your process and decrypted only after they arrive back — the server never sees plaintext.
|
|
|
|
The API mirrors OpenAI's `ChatCompletion`, making it easy to integrate into existing code.
|
|
|
|
> **Note on streaming:** The API is non-streaming. Setting `stream: true` in a request is ignored server-side to maintain full response encryption.
|
|
|
|
---
|
|
|
|
## Simple Chat Completion
|
|
|
|
```javascript
|
|
import { SecureChatCompletion } from 'nomyo-js';
|
|
|
|
const client = new SecureChatCompletion({
|
|
apiKey: process.env.NOMYO_API_KEY,
|
|
});
|
|
|
|
const response = await client.create({
|
|
model: 'Qwen/Qwen3-0.6B',
|
|
messages: [{ role: 'user', content: 'Hello! How are you today?' }],
|
|
temperature: 0.7,
|
|
});
|
|
|
|
// Extract what you need, then let the response go out of scope promptly.
|
|
// This minimises the time decrypted data lives in process memory
|
|
// (reduces exposure from swap files, core dumps, or memory inspection).
|
|
const reply = response.choices[0].message.content;
|
|
console.log(reply);
|
|
```
|
|
|
|
### With a System Message
|
|
|
|
```javascript
|
|
const response = await client.create({
|
|
model: 'Qwen/Qwen3-0.6B',
|
|
messages: [
|
|
{ role: 'system', content: 'You are a helpful assistant.' },
|
|
{ role: 'user', content: 'What is the capital of France?' },
|
|
],
|
|
temperature: 0.7,
|
|
});
|
|
|
|
console.log(response.choices[0].message.content);
|
|
```
|
|
|
|
---
|
|
|
|
## API Key Authentication
|
|
|
|
```javascript
|
|
// Constructor-level key (used for all requests from this instance)
|
|
const client = new SecureChatCompletion({
|
|
apiKey: process.env.NOMYO_API_KEY,
|
|
});
|
|
|
|
// Per-request key override (takes precedence over constructor key)
|
|
const response = await client.create({
|
|
model: 'Qwen/Qwen3-0.6B',
|
|
messages: [{ role: 'user', content: 'Hello!' }],
|
|
api_key: 'override-key-for-this-request',
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## Security Tiers
|
|
|
|
Pass `security_tier` in the request to control hardware routing and isolation level:
|
|
|
|
|
|
| Tier | Use case |
|
|
| -------------- | ------------------------------------------------------- |
|
|
| `"standard"` | General secure inference (GPU) |
|
|
| `"high"` | Sensitive business data — enforces secure tokenizer |
|
|
| `"maximum"` | HIPAA PHI, classified data — E2EE, maximum isolation |
|
|
|
|
```javascript
|
|
// Standard — general use
|
|
const response = await client.create({
|
|
model: 'Qwen/Qwen3-0.6B',
|
|
messages: [{ role: 'user', content: 'General query' }],
|
|
security_tier: 'standard',
|
|
});
|
|
|
|
// High — sensitive business data
|
|
const response2 = await client.create({
|
|
model: 'Qwen/Qwen3-0.6B',
|
|
messages: [{ role: 'user', content: 'Summarise this contract clause...' }],
|
|
security_tier: 'high',
|
|
});
|
|
|
|
// Maximum — PHI / classified data
|
|
const response3 = await client.create({
|
|
model: 'Qwen/Qwen3-0.6B',
|
|
messages: [{ role: 'user', content: 'Patient record summary...' }],
|
|
security_tier: 'maximum',
|
|
});
|
|
```
|
|
|
|
> Using `"high"` or `"maximum"` adds latency vs `"standard"` due to additional isolation measures.
|
|
|
|
---
|
|
|
|
## Using Tools (Function Calling)
|
|
|
|
```javascript
|
|
const response = await client.create({
|
|
model: 'Qwen/Qwen3-0.6B',
|
|
messages: [{ role: 'user', content: "What's the weather in Paris?" }],
|
|
tools: [
|
|
{
|
|
type: 'function',
|
|
function: {
|
|
name: 'get_weather',
|
|
description: 'Get weather information for a location',
|
|
parameters: {
|
|
type: 'object',
|
|
properties: {
|
|
location: { type: 'string', description: 'City name' },
|
|
},
|
|
required: ['location'],
|
|
},
|
|
},
|
|
},
|
|
],
|
|
tool_choice: 'auto',
|
|
temperature: 0.7,
|
|
});
|
|
|
|
const message = response.choices[0].message;
|
|
if (message.tool_calls) {
|
|
const call = message.tool_calls[0];
|
|
console.log('Tool called:', call.function.name);
|
|
console.log('Arguments:', call.function.arguments);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Error Handling
|
|
|
|
Import typed error classes to distinguish failure modes:
|
|
|
|
```javascript
|
|
import {
|
|
SecureChatCompletion,
|
|
AuthenticationError,
|
|
RateLimitError,
|
|
InvalidRequestError,
|
|
ForbiddenError,
|
|
ServerError,
|
|
ServiceUnavailableError,
|
|
APIConnectionError,
|
|
SecurityError,
|
|
} from 'nomyo-js';
|
|
|
|
const client = new SecureChatCompletion({ apiKey: process.env.NOMYO_API_KEY });
|
|
|
|
try {
|
|
const response = await client.create({
|
|
model: 'Qwen/Qwen3-0.6B',
|
|
messages: [{ role: 'user', content: 'Hello!' }],
|
|
});
|
|
console.log(response.choices[0].message.content);
|
|
|
|
} catch (err) {
|
|
if (err instanceof AuthenticationError) {
|
|
console.error('Bad API key:', err.message);
|
|
|
|
} else if (err instanceof RateLimitError) {
|
|
// The client already retried automatically (default: 2 retries).
|
|
// If you reach here, all retries were exhausted.
|
|
console.error('Rate limit exceeded after retries:', err.message);
|
|
|
|
} else if (err instanceof ForbiddenError) {
|
|
// Model not allowed for the requested security_tier
|
|
console.error('Forbidden:', err.message);
|
|
|
|
} else if (err instanceof InvalidRequestError) {
|
|
console.error('Bad request:', err.message);
|
|
|
|
} else if (err instanceof ServerError || err instanceof ServiceUnavailableError) {
|
|
console.error('Server error (retries exhausted):', err.message);
|
|
|
|
} else if (err instanceof APIConnectionError) {
|
|
console.error('Network error (retries exhausted):', err.message);
|
|
|
|
} else if (err instanceof SecurityError) {
|
|
console.error('Encryption/decryption failure:', err.message);
|
|
|
|
} else {
|
|
throw err; // re-throw unexpected errors
|
|
}
|
|
}
|
|
```
|
|
|
|
All typed errors expose:
|
|
|
|
- `message: string` — human-readable description
|
|
- `statusCode?: number` — HTTP status (where applicable)
|
|
- `errorDetails?: object` — raw response body (where applicable)
|
|
|
|
---
|
|
|
|
## Resource Management
|
|
|
|
Always call `dispose()` when you're done with a client to stop the background key-rotation timer and zero in-memory key material:
|
|
|
|
```javascript
|
|
const client = new SecureChatCompletion({ apiKey: process.env.NOMYO_API_KEY });
|
|
|
|
try {
|
|
const response = await client.create({ ... });
|
|
console.log(response.choices[0].message.content);
|
|
} finally {
|
|
client.dispose();
|
|
}
|
|
```
|
|
|
|
For long-running servers (HTTP handlers, daemons), create one client instance and reuse it — don't create a new one per request.
|
|
|
|
---
|
|
|
|
## `acreate()` Alias
|
|
|
|
`acreate()` is a direct alias for `create()` provided for code that follows the OpenAI naming convention:
|
|
|
|
```javascript
|
|
const response = await client.acreate({
|
|
model: 'Qwen/Qwen3-0.6B',
|
|
messages: [{ role: 'user', content: 'Hello!' }],
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## Browser Usage
|
|
|
|
In browsers, keys are kept in memory only (no file system). Everything else is identical to Node.js.
|
|
|
|
```html
|
|
<script type="module">
|
|
import { SecureChatCompletion } from 'https://unpkg.com/nomyo-js/dist/browser/index.js';
|
|
|
|
const client = new SecureChatCompletion({
|
|
baseUrl: 'https://api.nomyo.ai',
|
|
apiKey: 'your-api-key',
|
|
});
|
|
|
|
const response = await client.create({
|
|
model: 'Qwen/Qwen3-0.6B',
|
|
messages: [{ role: 'user', content: 'Hello from the browser!' }],
|
|
});
|
|
|
|
console.log(response.choices[0].message.content);
|
|
client.dispose();
|
|
</script>
|
|
```
|
|
|
|
> **Security note:** Embedding API keys in browser-side code exposes them to end users. In a real application, proxy requests through your backend or use short-lived tokens.
|
|
|
|
---
|
|
|
|
## Local Development (HTTP)
|
|
|
|
For a local NOMYO router running over plain HTTP:
|
|
|
|
```javascript
|
|
const client = new SecureChatCompletion({
|
|
baseUrl: 'http://localhost:12435',
|
|
allowHttp: true, // required; prints a security warning
|
|
});
|
|
```
|
|
|
|
Never use `allowHttp: true` in production.
|