@smooai/smooth-operator-core 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +105 -0
  2. package/package.json +1 -1
package/README.md ADDED
@@ -0,0 +1,105 @@
1
+ <p align="center">
2
+ <a href="https://smoo.ai"><img src="https://raw.githubusercontent.com/SmooAI/smooth-operator-core/main/.github/banner-typescript.png" alt="smooth-operator-core — The TypeScript engine for orchestrated AI agents" width="100%" /></a>
3
+ </p>
4
+
5
+ <p align="center">
6
+ <a href="https://smoo.ai/th"><img src="https://img.shields.io/badge/Smoo_AI-platform-00A6A6?style=for-the-badge&labelColor=020618" alt="Smoo AI"></a>
7
+ <a href="https://github.com/SmooAI/smooth-operator-core/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-F49F0A?style=for-the-badge&labelColor=020618" alt="license"></a>
8
+ <a href="https://lom.smoo.ai"><img src="https://img.shields.io/badge/hosted-lom.smoo.ai-FF6B6C?style=for-the-badge&labelColor=020618" alt="lom.smoo.ai"></a>
9
+ </p>
10
+
11
+ <p align="center">
12
+ <a href="https://www.npmjs.com/package/@smooai/smooth-operator-core"><img src="https://img.shields.io/npm/v/@smooai/smooth-operator-core?style=flat-square&color=00A6A6&labelColor=020618" alt="npm"></a>
13
+ <img src="https://img.shields.io/badge/TypeScript-engine-3178C6?style=flat-square&labelColor=020618" alt="TypeScript engine">
14
+ </p>
15
+
16
+ ---
17
+
18
+ > The TypeScript sibling of the [Rust reference engine](https://github.com/SmooAI/smooth-operator-core). Agents, tools, knowledge/RAG, memory, checkpointing, human-in-the-loop, cost budgets, and workflows — as one embeddable npm package. It's the engine, not a notebook demo.
19
+
20
+ `@smooai/smooth-operator-core` is the **native TypeScript implementation** of the Smoo AI agent engine — the in-process observe→think→act loop that powers [**lom.smoo.ai**](https://lom.smoo.ai). It's a sibling of the [Rust reference engine](https://github.com/SmooAI/smooth-operator-core) and one of the [polyglot set](https://github.com/SmooAI/smooth-operator-core/blob/main/docs/Polyglot-Engines.md) (Rust, TypeScript, Python, Go, C#/.NET) whose behavior is held at parity by a shared eval suite.
21
+
22
+ It's a library, not a client to a remote server: it *is* the agent, running in your Node process. Every surface is covered by **fast, offline tests** built on a deterministic `MockLlmProvider`, so the loop is verified — not vibe-coded.
23
+
24
+ ## Install
25
+
26
+ ```bash
27
+ npm install @smooai/smooth-operator-core
28
+ ```
29
+
30
+ ## Quickstart
31
+
32
+ A complete agent — no credentials needed — using the deterministic mock provider the engine's own tests run on:
33
+
34
+ ```ts
35
+ import { SmoothAgent, MockLlmProvider } from '@smooai/smooth-operator-core';
36
+
37
+ const provider = new MockLlmProvider().pushText('the answer is 42');
38
+ const agent = new SmoothAgent(provider, { instructions: 'You are a helpful assistant' });
39
+
40
+ const response = await agent.run('what is the answer?');
41
+ console.log(response.text);
42
+ ```
43
+
44
+ `SmoothAgent`'s constructor takes a `ChatClientLike` (the `MockLlmProvider` implements it — swap in any OpenAI-compatible client) and an `AgentOptions` object. `run` returns an `AgentRunResponse` whose `text` is the final answer.
45
+
46
+ ## Features
47
+
48
+ The full parity surface — every engine in the [polyglot set](https://github.com/SmooAI/smooth-operator-core/blob/main/docs/Polyglot-Engines.md) ships it:
49
+
50
+ - **Agentic tool-calling loop** — observe→think→act, looping until the model answers.
51
+ - **Typed tools** — register `Tool`s the model can call, with parallel dispatch.
52
+ - **Knowledge / RAG + vectors** — `InMemoryKnowledge` / `VectorKnowledge` ground the turn in retrieved documents.
53
+ - **Memory** — `InMemoryMemory` recalls long-term entries into context each turn.
54
+ - **Compaction** — a sliding-window token budget keeps the prompt under a ceiling.
55
+ - **Cost / budget** — `CostTracker` + `CostBudget` with per-model pricing and early stop.
56
+ - **Checkpointing** — `InMemoryCheckpointStore` (and the `CheckpointStore` seam) persist/resume a conversation.
57
+ - **Rerank** — `LexicalReranker` reranks retrieved hits before injection.
58
+ - **Sub-agents / delegation** — `delegateTool` spawns child agents for sub-tasks.
59
+ - **Cast + clearance** — `Cast`, `Clearance`, `makeRole` for per-role tool-access policy.
60
+ - **Human-in-the-loop gate** — `HumanGate` requires approval before designated tool calls run.
61
+ - **Conversation thread** — `SmoothAgentThread` carries a conversation across multiple `run` calls.
62
+ - **`LlmProvider` seam + `MockLlmProvider`** — inject any OpenAI-compatible client; the record/replay mock drives the offline tests.
63
+ - **Deferred tools + `tool_search`** — `ToolSearch` hides rarely-used tool schemas behind a meta-tool the model calls to promote the ones it needs.
64
+ - **Typed workflow graph** — `Workflow` with typed nodes/edges, alongside the agent loop.
65
+ - **Parallel tool calls** — dispatch ≥2 tool calls concurrently (transcript order preserved).
66
+ - **Retry / backoff** — retry transient model-call failures with exponential backoff.
67
+ - **Streaming** — stream incremental text, tool calls, and tool results as the turn runs.
68
+
69
+ ## Streaming
70
+
71
+ `runStream` is an async generator over a `StreamEvent` tagged union (discriminated on `type`): `text` deltas as the model produces them, each `tool_call` before dispatch, each `tool_result` after it finishes, and a terminal `done` event carrying the same response `run` would have returned.
72
+
73
+ ```ts
74
+ for await (const event of agent.runStream('what is the answer?')) {
75
+ if (event.type === 'text') process.stdout.write(event.text);
76
+ if (event.type === 'done') console.log(`\n${event.response.text}`);
77
+ }
78
+ ```
79
+
80
+ `runStream` requires a streaming-capable client (`chat.completions.createStream`); the `MockLlmProvider` supplies one, replaying the same script as the non-streaming path.
81
+
82
+ ## Part of Smoo AI
83
+
84
+ `smooth-operator-core` is built and open-sourced by **[Smoo AI](https://smoo.ai)** — the AI-powered business platform with AI built into every product: CRM, customer support, campaigns, field service, observability, and developer tools.
85
+
86
+ - 🚀 **Smooth on the platform** — [smoo.ai/th](https://smoo.ai/th)
87
+ - 🧰 **More open source from Smoo AI** — [smoo.ai/open-source](https://smoo.ai/open-source)
88
+ - 🧩 **Run it hosted** — [lom.smoo.ai](https://lom.smoo.ai)
89
+
90
+ ## Links
91
+
92
+ - [**lom.smoo.ai**](https://lom.smoo.ai) — run it hosted
93
+ - [smooth-operator-core](https://github.com/SmooAI/smooth-operator-core) — the polyglot engine repo
94
+ - [Polyglot Engines](https://github.com/SmooAI/smooth-operator-core/blob/main/docs/Polyglot-Engines.md) — install + hello-agent in all five languages
95
+ - [smoo.ai](https://smoo.ai) — the product · [smoo.ai/open-source](https://smoo.ai/open-source) — more open source
96
+
97
+ ## License
98
+
99
+ MIT — see [LICENSE](https://github.com/SmooAI/smooth-operator-core/blob/main/LICENSE).
100
+
101
+ ---
102
+
103
+ <p align="center">
104
+ Built by <a href="https://smoo.ai"><strong>Smoo AI</strong></a> — AI built into every product.
105
+ </p>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@smooai/smooth-operator-core",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Native TypeScript implementation of the smooth-operator agent engine — an in-process, OpenAI-compatible agentic tool-calling loop with knowledge grounding. The TypeScript sibling of the Rust reference engine, the C# core, and the Python core.",
5
5
  "type": "module",
6
6
  "license": "MIT",