@semoss\sdk

@semoss\sdk is a small utility package that accelerates the process of building an app.

Getting Started:

First, install the sdk using a package manager (or your favorite cdn):

npm install @semoss/sdk

Next, import the Insight from the SDK and create a new instance of it. Insights are temporal workspaces that allow end users to script and interact with a model, storage engine, or database.

import { Insight } from "@semoss/sdk";

const insight = new Insight();

Once the application is mounted, initialize the insight and load your data app into the insight;

await insight.initialize();

Now you are ready to go. You can do things like

• Login or Logout

const login = (username, password) => {
    const success = await insight.actions.login({
        type: 'native',
        username: username,
        password: password,
    });

    console.log(success);
};

const loginWithOauth = (provider: 'ms' ) => {
    const resp = await insight.actions.login({
        type: 'oauth',
        provider: provider
    })

    console.log(resp)
}

const logout = (username, password) => {
    const success = await insight.actions.logout();

    console.log(success);
};

• Ask a LLM and return a result

const ask = (question) => {
    const { output } = await insight.actions.askModel(MODEL_ID, question);

    // log the output
    console.log(output);
};

• Ask LLM with stream

import { partial, runPixel } from "@semoss/sdk";

const insight = new Insight();
await insight.initialize();
const insightId = insight._store.insightId;

const askWithStream = async () => {
    let isCollecting = false;

    const collectMessage = async () => {
        // only continue if response hasn't come back from runPixel
        if (!isCollecting) {
            return;
        }

        // get the output of partial
        try {
            const output = await partial(insightId);

            // add the partial
            if (output.message && output.message.total) {
                setAnswer(output.message.total);
            }

            // get the next partial of response
            setTimeout(() => collectMessage(), 1000);
        } catch (e) {
            // noop
        }
    };

    // start collecting
    isCollecting = true;

    // initial delay that collects partial of response
    setTimeout(() => collectMessage(), 500);

    const { errors, pixelReturn } = await runPixel(
        `LLM(engine=["001510f8-b86e-492e-a7f0-41299775e7d9"], command=["<encode>${question}</encode>"]);`,
        insightId,
    );

    isCollecting = false;
};

• Run a database query

const getMovies = () => {
    const { output } = await insight.actions.queryDatabase(
        DATABASE_ID,
        'select * from movie',
    );

    // log the output
    console.log(output);
};

• Run Python

const sum = (num1, num2) => {
    const { output } = await insight.actions.runPy(`${num1} + ${num2}`);

    // log the output
    console.log(output);
};

• Upload a File

const upload = (file, path) => {
    const { output } = await insight.actions.upload(file, path);

    // log the output
    console.log(output);
};

• Download a File

const download = (path) => {
    const { output } = await insight.actions.download(path);

    // log the output
    console.log(output);
};

• Run an MCP tool and send the response to the room

const runMCPTool = (name, parameters,)  => {
    const { output } = await insight.actions.runMCPTool(name, parameters);

    // log the output
    console.log(output);
};

Testing

This package uses Vitest for unit tests.

Running Tests

# run all tests
npx vitest

# run in watch mode
npx vitest --watch

# run with coverage
npx vitest --coverage

What's Tested

| Area | Files | Notes | |---|---|---| | Utilities | src/utility/fetch.ts, src/utility/error.ts, src/utility/embed-auth.ts | HTTP wrappers, custom errors, embed auth flow | | Environment | src/env.ts | Singleton getters and update() | | API wrappers | src/api/base.ts, src/api/auth.ts, src/api/file.ts, and others | Fetch is mocked via vi.stubGlobal | | React hooks | src/js-frameworks/react/hooks/ | Rendered with @testing-library/react; timers use vi.useFakeTimers() |

Writing Tests

Place test files next to the source file they cover, e.g.:

src/utility/fetch.ts
src/utility/fetch.test.ts

🔄 Migration Guide

For Users Migrating from @semoss/sdk-react

If you are a user migrating from [@semoss/sdk-react] to [@semoss/sdk], this section will help you with the transition.

Key Change

• React hooks, contexts, and utilities have been moved to our centralized javascript software development kit

Migration Steps

1. Uninstall the old package @semoss/sdk-react
2. Swap import statements, any module that was once imported from @semoss/sdk-react can now be imported from @semoss/sdk/react

Eg.

import { useInsight } from '@semoss/sdk-react'

Should now import as such:

import { useInsight } from '@semoss/sdk/react'

Tips and Tricks

Here are a few tips and tricks that can help streamline the development process.

Development Environment

Note: We recommend manually setting the environment only in development mode.

You can setup a development environment and use access keys to authenticate with the app server. Generate the keys on the server and then update the Env module. See:

// import the module
import { Env } from "@semoss/sdk";

// update the environment
Env.update({
    /**
     * Url pointing to the app server
     **/
    MODULE: "",
    /**
     * Access key generated by the app server
     **/
    ACCESS_KEY: "",
    /**
     * Secret key generated by the app server
     **/
    SECRET_KEY: "",
    /**
     * Optional field. This will load app specific reactors into the insight. Your app has to be hosted and running on the app server.
     **/
    APP: "",
});

Note: Please do not commit your keys. Instead externalize your keys to a .env and load them in as environment variables during development

Python

The app server allows you to write custom python to power your app. You can initialize your python environment by:

1. Loading via js

Set the option on initialize:

// define it int he js
const py = `
def sayHello(name):
    print(f'Hello {name}')
`;

// update the environment
insight.initialize({
    python: {
        /**
         *  Load the python via js
         **/
        type: "script",
        /**
         *  Path to the file
         **/
        script: py,
        /**
         *  Alias for the file
         **/
        alias: "smss",
    },
});

2. Loading via a file

The sdk will load python via an external file.

# ./hello.py
def sayHello(name):
    print(f'Hello {name}')

Set the option on initialize:

// update the environment
insight.initialize({
    python: {
        /**
         *  Load the python via an external file
         **/
        type: "file",
        /**
         *  Path to the file
         **/
        path: "./hello.py",
        /**
         *  Alias for the file
         **/
        alias: "smss",
    },
});

Next you can call the preloaded python methods by calling the runPy action. See

const hello = (name) => {
    const { output } = await insight.actions.runPy(`smss.sayHello(${name})`);

    // log the output
    console.log(output);
};

AI Coding Assistant Setup

@semoss/sdk ships AI agent skills alongside its source code. These skills give your AI coding assistant (GitHub Copilot, Claude Code, Cursor, etc.) built-in knowledge of the SDK's APIs — including the room API, pixel calls, and hook patterns — without you having to paste docs into chat.

Skills are bundled under node_modules/@semoss/sdk/skills/ and follow the Agent Skills open standard, making them compatible with npm-skills and skills-npm.

One-time extraction

Run extraction into your agent's discovery directory after installing the SDK:

# GitHub Copilot
npx npm-skills extract --output .github/skills

# Claude Code / generic agents
npx npm-skills extract --output .agents/skills

# Cursor
npx npm-skills extract --output .cursor/skills

Keep skills in sync automatically

Add a postinstall script so skills update whenever you upgrade the SDK:

{
    "scripts": {
        "postinstall": "npm-skills extract --skip-production --override --output .github/skills"
    },
    "devDependencies": {
        "npm-skills": "latest"
    }
}

Or configure the output path once and just run npm run skills:extract:

{
    "scripts": {
        "skills:extract": "npm-skills extract --override"
    },
    "npmSkills": {
        "consume": {
            "output": ".github/skills"
        }
    }
}

What gets installed

| Skill | Covers | |-------|--------| | sdk-chat | Creating rooms, sending messages, fetching room options, updating config, binding rooms to insights |

Skills are versioned with the SDK — upgrading @semoss/sdk and re-running extraction keeps your assistant's knowledge current.