Nexus AI

TypeScript SDK, CLI, web workspace, and AWS SAM deployment scaffold for Nexus AI.

Overview

Nexus AI brings together a programmable SDK, a terminal CLI, a browser workspace, and a straightforward AWS deployment path.

The repo is designed to be easy to adopt in stages. You can call the API from code, use the CLI for quick workflows, open the browser workspace for interactive work with files and chats, or deploy the API with AWS SAM.

At a glance, Nexus AI includes:

• a TypeScript SDK for API access
• a CLI for status checks, provider discovery, and queries
• a browser workspace for chats, uploads, generated files, and exports
• an AWS SAM template for Lambda and API Gateway deployment
• a small contract layer for stable request and response shapes

Features

• Multi-provider support across Anthropic, OpenAI, Google, Mistral, and Ollama
• Query modes for standard, context, graph, and rag
• A browser workspace with saved chats, file uploads, live model availability, and request-aware exports
• SDK helpers for direct HTTP access and a higher-level app context
• CLI commands for status, providers, models, tools, and queries
• AWS-ready deployment with Lambda and API Gateway

Quick Start

Install dependencies:

npm install

Build the package:

npm run build

Run the main checks:

npm run verify

Open the browser workspace:

https://rotsl.github.io/nexus-ai/

Try the CLI against a deployed API:

export NEXUS_API_BASE_URL="https://your-api-id.execute-api.region.amazonaws.com"
node dist/main.js status
node dist/main.js "Explain what Nexus AI does"

Inspect the package output before release:

npm pack --dry-run

Environment

Environment loading is handled automatically through src/env/loadEnv.ts.

Start from .env.example.

Typical client values:

NEXUS_API_BASE_URL=
NEXUS_API_KEY=

Deployment-related values:

AWS_REGION=
LOG_LEVEL=info
PUBLIC_APP_ORIGIN=https://rotsl.github.io
ANTHROPIC_API_KEY=
OPENAI_API_KEY=
GOOGLE_API_KEY=
GEMINI_API_KEY=
MISTRAL_API_KEY=
OLLAMA_BASE_URL=http://localhost:11434

In the browser workspace, users can save provider keys locally in the browser, clear them at any time, and work with uploaded files directly from the UI.

SDK

The main SDK entrypoint is src/index.ts.

Example:

import { NexusApiClient } from '@rotsl/nexus-ai';

const client = new NexusApiClient({
  baseUrl: process.env.NEXUS_API_BASE_URL,
  apiKey: process.env.NEXUS_API_KEY,
});

const status = await client.status();
const providers = await client.providers();

Install from npm with:

npm install @rotsl/nexus-ai

For a higher-level interface, src/AppContext.ts exposes helpers such as:

• initialize()
• query()
• contextQuery()
• graphQuery()
• ragQuery()
• status()
• listProviders()
• listTools()
• listAllModels()

CLI

The CLI lives in src/main.ts.

Examples:

node dist/main.js status

node dist/main.js providers

node dist/main.js "Summarize this project"

node dist/main.js query \
  --mode context \
  --message "Summarize this codebase" \
  --source package.json src

API

Request and response schemas live in src/contracts.ts.

Available endpoints:

• GET /v1/status
• GET /v1/providers
• GET /v1/tools
• GET /v1/models
• POST /v1/query

POST /v1/query accepts fields such as:

• message
• mode
• provider
• model
• maxTokens
• sources

Supported query modes:

• standard
• context
• graph
• rag

Web Workspace

The web workspace is built from docs/index.html, docs/script.js, and docs/styles.css.

It includes:

• a persistent chat interface with saved chats
• live provider and model browsing
• file upload and download flows
• structured markdown and code rendering
• browser-saved provider settings
• generated files saved back into the workspace
• request-aware export actions for formats such as Markdown, Word, PDF, ZIP, and common code outputs

The workspace is intended for day-to-day interactive use: bringing in files, continuing multi-turn chats, cross-referencing earlier chats, and saving generated outputs without leaving the browser.

Deployment

AWS deployment is defined by template.yaml and samconfig.toml.

Common commands:

sam build --template-file template.yaml

sam local start-api --template-file template.yaml

sam deploy --guided --template-file template.yaml

After deployment:

export NEXUS_API_BASE_URL="https://your-api-id.execute-api.region.amazonaws.com"

Quick checks:

curl "$NEXUS_API_BASE_URL/v1/status" \
  -H "x-nexus-api-key: $NEXUS_API_KEY"

curl -X POST "$NEXUS_API_BASE_URL/v1/query" \
  -H "content-type: application/json" \
  -H "x-nexus-api-key: $NEXUS_API_KEY" \
  -d '{"message":"Explain what Nexus AI does","mode":"standard"}'

Quality Checks

CI runs from .github/workflows/ci.yml and covers:

• Node 20
• Node 22
• npm run verify
• npm pack --dry-run
• docs JavaScript syntax validation

Useful local checks:

npm run verify
node --check docs/script.js
npm pack --dry-run

Package

The package metadata and scripts live in package.json.

If you change package layout, CLI behavior, SDK contracts, or deployment scripts, it is worth running:

npm run verify
npm pack --dry-run

Contributing

See CONTRIBUTING.md.