Stackspot

---

Content

* Installation
* Usage
* ⚙ Configuration
* 🌐 Using behind proxy
* Methods
* ✨ AI
* AI - KS - Create a new Knowledge Source
* AI - KS - Upload new file to a Knowledge Source
* AI - KS - Remove files from a Knowledge Source
* AI - Agents - Send prompt (non-streaming)
* AI - Agents - Send prompt (streaming)
* AI - Agents - Send prompt with file upload
* AI - Quick Command - Create a new execution
* AI - Quick Command - Get execution
* AI - Quick Command - Poll execution until it's done
* 🗝️ Auth
* Auth - Get the access token
* License

---

Installation

To install, simply add the package using npm, yarn, pnpm, etc...

``bash
npm install stackspot
`

---

Usage

You can start using the global instance:

`javascript
import { Stackspot } from 'stackspot';

// By default, the global instance will configure itself using the environment variables:
// - STACKSPOT_CLIENT_ID
// - STACKSPOT_CLIENT_SECRET
// - STACKSPOT_REALM

// Creating a new 'Knowledge Source' for example:
await Stackspot.instance.ai.ks.createKs('new-ks-test', 'New KS test', 'This is a test KS', 'CUSTOM');
`

---

$3

You can configure the global instance:

`javascript
// Using the 'config(opts)' method, to update all the settings at once:
Stackspot.instance.config({
clientId: '...',
clientSecret: '...',
realm: '...',
agent: myHttpAgent
});

// Or update them individually:
Stackspot.instance
.setClientId('...')
.setClientSecret('...');
`

If you want to create your own Stackspot instance, you can either pass the settings on the constructor, use the 'config' method, or configure individual properties as well:

`javascript
// Creating a new stackspot instance (instead of using the 'global' one):
const myInstance = new Stackspot({ clientId: '...', clientSecret: '...', realm: '...' });


// If you want, it's possible to call the 'config(opts)' method of this instance as well to update the settings:
myInstance.config({ ... });


// Or configure properties individually:
myInstance.setClientId('...');
`

---

$3

Internally it uses node-fetch to make requests, so you can provide a custom HTTP agent to configure proxy and SSL certificates.

Example using proxy-agent:

`javascript
import { Stackspot } from 'stackspot';
import { ProxyAgent } from 'proxy-agent';

// ProxyAgent will use environment variables to configure proxy like HTTP_PROXY, HTTPS_PROXY and NO_PROXY.
Stackspot.instance.setAgent(new ProxyAgent());
`

---

Methods

Here are all the available methods of this package:

$3

All the AI related functions are bellow Stackspot.instance.ai namespace.

#### AI - KS - Create a new Knowledge Source

To create a new _Knowledge Source_, just run:

`javascript
await Stackspot.instance.ai.ks.createKs('my-new-ks', 'My new KS', 'A test KS', 'CUSTOM');
`

For more info about the KS creation, check out the official documentation: https://ai.stackspot.com/docs/knowledge-source/create-knowledge-source

#### AI - KS - Upload new file to a Knowledge Source

You can add or update existing objects inside a _Knowledge Source_:


`javascript
// This creates/updates a KS object named 'test.txt' containing 'Hello World' text:
await Stackspot.instance.ai.ks.uploadKsObject('my-ks-slug', 'test.txt', 'Hello World');
`

`javascript
// Assuming you have a file in ./my-file.txt:
const fileContent = await fs.promises.readFile('./my-file.txt', 'utf8');

await Stackspot.instance.ai.ks.uploadKsObject('my-ks-slug', 'test.txt', fileContent);
`

#### AI - KS - Remove files from a Knowledge Source

To batch remove files from a _Knowledge Source_:

`javascript
// This removes ALL objects from the KS:
await Stackspot.instance.ai.ks.batchRemoveKsObjects('my-ks-slug', 'ALL');
`

`javascript
// This removes only the STANDALONE objects from the KS:
await Stackspot.instance.ai.ks.batchRemoveKsObjects('my-ks-slug', 'STANDALONE');
`

`javascript
// This removes only the UPLOADED objects from the KS:
await Stackspot.instance.ai.ks.batchRemoveKsObjects('my-ks-slug', 'UPLOADED');
`

#### AI - Agents - Send prompt (non-streaming)

To send a prompt to an Agent and get the full response at once (no streaming):

`javascript
// Calling the agent:
const res = await Stackspot.instance.ai.agents.sendPrompt('my-agent-id', 'Hello agent!');

console.log(res.message); // Full response message
`

You can optionally enable Stackspot Knowledge and/or ask the API to return KS info in the response:

`javascript
const res = await Stackspot.instance.ai.agents.sendPrompt(
'my-agent-id',
'Answer using the knowledge base if needed.',
{
stackspot_knowledge: true,
return_ks_in_response: true,
}
);

console.log(res.message); // Full response message
`

#### AI - Agents - Send prompt (streaming)

For real-time tokens, use the streaming API. It returns an object with a collector and an eventEmitter:

`javascript
const { collector, eventEmitter } = await Stackspot.instance.ai.agents.sendPromptStreaming(
'my-agent-id',
'A list of best movies to watch'
);

// Listen to partial lines as they arrive:
eventEmitter.on('line', (line, data) => {
// Each JSON line may contain a partial message
if (data?.message)
process.stdout.write(json.message);
});

// Handle errors:
eventEmitter.on('error', (err) => {
console.error('Streaming error:', err);
});

// Called when the stream is closed:
eventEmitter.on('close', (code) => {
console.log('\nStream closed with code:', code);
console.log('Final assembled message:', collector.messageBuffer);
});
`

If you prefer the raw Node.js stream, you can use sendPromptStreamingRaw(agentId, prompt, opts) which returns the underlying stream body.

#### AI - Agents - Send prompt with file upload

You can upload a file to be used by the Agent in the context of a prompt. First upload the file, then send your prompt referencing the returned upload.id:

`javascript
// Upload a file (Buffer or string):
const upload = await Stackspot.instance.ai.agents.uploadFileForAgents(
'notes.txt',
'These are my notes the agent should consider.'
);

// Send the prompt referencing the uploaded content:
const res = await Stackspot.instance.ai.agents.sendPrompt(
'my-agent-id',
'Please summarize the uploaded notes.',
{
upload_ids: [upload.id],
}
);

console.log(res.message);
`

You can also read the file from disk:

`javascript
const content = await fs.promises.readFile('./notes.txt'); // Buffer
await Stackspot.instance.ai.agents.uploadFileForAgents('notes.txt', content);
`

#### AI - Quick Command - Create a new execution

To manually create a new _Quick Command_ execution:

`javascript
const executionId = await Stackspot.instance.ai.quickCommand.createExecution('my-quick-command-slug', 'Input for this execution');
// Return example: "06J85YZZ5HVO1XXCKKR4TJ16N2"
`

#### AI - Quick Command - Get execution

After creating a new _Quick Command_ execution, you may want to check it to see if it has completed successfully, and get its result:

`javascript
const execution = await Stackspot.instance.ai.quickCommand.getExecution('06J85YZZ5HVO1XXCKKR4TJ16N2');

console.log('status: ' + execution.progress?.status);
`

_Obs.: Note that, at the time this call have been made, the execution may not yet be done, so you have to write some polling logic, or use the 'pollExecution' method._

#### AI - Quick Command - Poll execution until it's done

It can be cumbersome to write the logic to poll a _Quick Command_ execution after its creation to check if it's done. This library gets you covered on that:

`javascript
// Just create a new execution:
const executionId = await Stackspot.instance.ai.quickCommand.createExecution('my-quick-command-slug', 'Input for this execution');

// And call the poll method:
// This will check the execution status until it's done and then return the execution object:
const execution = await Stackspot.instance.ai.quickCommand.pollExecution(executionId);

console.log('status: ' + execution.progress?.status); // 'COMPLETED'
console.log('result: ' + execution.result); // The Quick Command result.
`

---

$3

The library methods already handles the authentication process, but you can access the auth methods by yourself using the Stackspot.instance.auth namespace:

#### Auth - Get the access token

This will get the cached token, or fetch a new one if they aren't valid anymore:

`javascript
await Stackspot.instance.auth.getAccessToken();
`

_Obs.: To configure the authentication properties like clientId, clientSecret, and realm`, head back to the Usage section._

---

License

[npm-image]: https://img.shields.io/npm/v/stackspot.svg
[npm-url]: https://npmjs.org/package/stackspot