npm package: @rotsl/nexus-ai
Description: Public Nexus AI client, thin CLI, and AWS SAM scaffold for the serverless runtime API.
Author: Rohan R
Latest version: 1.0.0

# Nexus AI

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

[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
[![CI](https://github.com/rotsl/nexus-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/rotsl/nexus-ai/actions/workflows/ci.yml)
[![Pages](https://github.com/rotsl/nexus-ai/actions/workflows/pages.yml/badge.svg)](https://github.com/rotsl/nexus-ai/actions/workflows/pages.yml)
[![TypeScript 5.9](https://img.shields.io/badge/typescript-5.9-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![npm pack checked](https://img.shields.io/badge/package-checked-16a34a)](https://github.com/rotsl/nexus-ai)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

## 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:

```bash
npm install
```

Build the package:

```bash
npm run build
```

Run the main checks:

```bash
npm run verify
```

Open the browser workspace:

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

Try the CLI against a deployed API:

```bash
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:

```bash
npm pack --dry-run
```

## Environment

Environment loading is handled automatically through [src/env/loadEnv.ts](/Users/wot25kir/nexus-ai/src/env/loadEnv.ts).

Start from [.env.example](/Users/wot25kir/nexus-ai/.env.example).

Typical client values:

```bash
NEXUS_API_BASE_URL=
NEXUS_API_KEY=
```

Deployment-related values:

```bash
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](/Users/wot25kir/nexus-ai/src/index.ts).

Example:

```ts
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:

```bash
npm install @rotsl/nexus-ai
```

For a higher-level interface, [src/AppContext.ts](/Users/wot25kir/nexus-ai/src/AppContext.ts) exposes helpers such as:

- `initialize()`
- `query()`
- `contextQuery()`
- `graphQuery()`
- `ragQuery()`
- `status()`
- `listProviders()`
- `listTools()`
- `listAllModels()`

## CLI

The CLI lives in [src/main.ts](/Users/wot25kir/nexus-ai/src/main.ts).

Examples:

```bash
node dist/main.js status
```

```bash
node dist/main.js providers
```

```bash
node dist/main.js "Summarize this project"
```

```bash
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](/Users/wot25kir/nexus-ai/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](/Users/wot25kir/nexus-ai/docs/index.html), [docs/script.js](/Users/wot25kir/nexus-ai/docs/script.js), and [docs/styles.css](/Users/wot25kir/nexus-ai/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](/Users/wot25kir/nexus-ai/template.yaml) and [samconfig.toml](/Users/wot25kir/nexus-ai/samconfig.toml).

Common commands:

```bash
sam build --template-file template.yaml
```

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

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

After deployment:

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

Quick checks:

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

```bash
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](/Users/wot25kir/nexus-ai/.github/workflows/ci.yml) and covers:

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

Useful local checks:

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

## Package

The package metadata and scripts live in [package.json](/Users/wot25kir/nexus-ai/package.json).

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

```bash
npm run verify
npm pack --dry-run
```

## Contributing

See [CONTRIBUTING.md](/Users/wot25kir/nexus-ai/CONTRIBUTING.md).