open-index/open-npm huggingface dataset:
npm package: @operor/cli
Description: CLI setup wizard and launcher for Operor
Latest version: 0.5.0

# @operor/cli

CLI tool for Operor — setup wizard, diagnostics, testing, and knowledge base management.

## Install

```bash
pnpm add -g @operor/cli
```

## Commands

### Setup & Runtime

```bash
operor setup    # Interactive setup wizard
operor start    # Start with existing .env config
operor status   # Show configuration status
operor doctor   # Validate config and test connections
operor test     # Run demo test scenarios
```

### Configuration

```bash
operor config show          # Show current config
operor config set KEY VALUE # Set a config value
operor config unset KEY     # Remove a config value
```

### Knowledge Base

Requires `KB_ENABLED=true` in `.env` (set via `operor setup` or `operor config set`).

```bash
# Ingest content
operor kb add-url <url>                    # Ingest a web page
operor kb add-file <path>                  # Ingest a document (PDF, TXT, MD, etc.)
operor kb add-faq <question> <answer>      # Add a manual FAQ entry

# Browse & search
operor kb list                             # List all documents
operor kb search <query>                   # Search with relevance scores
operor kb search <query> -n 10             # Search with custom result limit

# Manage
operor kb delete <id>                      # Delete a document by ID
operor kb stats                            # Show KB statistics (docs, chunks, DB size)
```

#### Examples

```bash
# Add your docs
operor kb add-url https://docs.example.com/faq
operor kb add-file ./product-manual.pdf
operor kb add-faq "What are your hours?" "We're open Mon-Fri 9am-5pm EST."

# Test retrieval
operor kb search "return policy"

# Check stats
operor kb stats
```

#### KB Configuration

Set during `operor setup` or manually via `operor config set`:

| Variable | Description | Default |
|---|---|---|
| `KB_ENABLED` | Enable knowledge base | `false` |
| `KB_DB_PATH` | SQLite database path | `./knowledge.db` |
| `KB_EMBEDDING_PROVIDER` | `openai`, `google`, `mistral`, `cohere`, or `ollama` | `openai` |
| `KB_EMBEDDING_MODEL` | Embedding model name | Provider default |
| `KB_EMBEDDING_API_KEY` | API key for embeddings | — |
npm package: @operor/core
Description: Agent OS Core - AI Agent Operating System
Latest version: 0.5.0

# @operor/core

Core framework for Operor — provides the agent runtime, message routing, intent classification, and extensibility points.

## Knowledge Base Integration

Agents can opt into knowledge base (KB) powered responses via configuration:

- `OperorConfig.knowledgeStore` — configure the KB backend (SQLite path, embedding provider/model, dimensions)
- `AgentConfig.knowledgeBase: true` — opt-in per agent to use KB for context retrieval

```typescript
const os = new Operor({
  knowledgeStore: {
    dbPath: './my-kb.db',
    embeddingProvider: 'openai',
    embeddingModel: 'text-embedding-3-small',
    dimensions: 1536,
  },
});

os.createAgent({
  name: 'support',
  triggers: ['*'],
  knowledgeBase: true, // this agent uses KB
});
```

## Training Mode

Training mode allows whitelisted phone numbers to manage KB content via chat commands.

```typescript
const os = new Operor({
  trainingMode: {
    enabled: true,
    whitelist: ['+1234567890'],
  },
});
```

Available commands (sent as chat messages by whitelisted users):

| Command | Description |
|---------|-------------|
| `/teach <content>` | Add knowledge to the KB |
| `/faq list` | List all FAQ entries |
| `/faq delete <id>` | Delete an FAQ entry |
| `/faq search <query>` | Search FAQ entries |
| `/test <question>` | Test KB response |
| `/status` | Show KB status |
| `/help` | Show available commands |

Training commands emit `training:command` events for external handlers to implement the actual KB operations.

## Guardrails

Per-agent guardrails control what messages are accepted and what responses are allowed.

```typescript
os.createAgent({
  name: 'support',
  triggers: ['*'],
  guardrails: {
    systemRules: ['Always be polite', 'Never share internal pricing'],
    blockedTopics: ['politics', 'religion'],
    escalationTriggers: ['speak to a human', 'talk to manager'],
    maxResponseLength: 2000,
  },
});
```

- `systemRules` — injected into the LLM system prompt
- `blockedTopics` — messages containing these topics are refused (case-insensitive substring match)
- `escalationTriggers` — phrases that trigger human handoff
- `maxResponseLength` — caps response character length

The `GuardrailEngine` class provides `checkInput()` and `checkOutput()` methods for use in agent processing pipelines.