@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);
};

• Query 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,
        );

         // OR

        // const response = await  insight.actions.run(
        //     `LLM(engine=[MODEL_ID], 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);
};

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 html (default)

The sdk will scan your html and load in html. Specifically, it will look for an data-semoss-py attribute to identify the code block and data-alias attribute to define the alias (default is smss). It's recommended to wrap your code in <pre></pre> to preserve formatting. An example:

<pre data-semoss-py data-alias="smss" hidden="true">
def sayHello(name):
    print(f'Hello {name}')
</pre

Set the option on initialize:

// update the environment
insight.initialize({
    python: {
        /**
         *  Manually search the html
         **/
        type: 'detect',
    },
});

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',
    },
});

3. 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',
    },
});

Next you can 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);
};