diff --git a/dotnet/core/README.md b/dotnet/core/README.md
index 7c04fba..c53758c 100644
--- a/dotnet/core/README.md
+++ b/dotnet/core/README.md
@@ -1,102 +1,96 @@
-# SmooAI.SmoothOperator.Core
-
-The **native C# implementation of the smooth-operator agent engine** — an in-process,
-NuGet-installable sibling of the Rust reference engine `smooai-smooth-operator-core`.
-It is **not** a client to a remote server: it *is* the agent, running in your .NET
-process.
-
-It's built on **`Microsoft.Extensions.AI`** and learns from **Microsoft Agent Framework**
-idioms, so it slots into the .NET AI ecosystem natively:
-
-- Any MEAI provider is the model (`IChatClient` — Azure OpenAI, OpenAI, Ollama, the
- smooth gateway, …).
-- A normal C# method is a tool (`AIFunctionFactory.Create`).
-- `RunAsync` / `RunStreamingAsync` (MAF naming).
-
-Behavioral parity with the Rust reference is enforced by the **shared conformance
-fixtures + eval scenarios**, not by identical type shapes — see
-[Polyglot Cores](https://github.com/SmooAI/smooth-operator/blob/main/docs/Architecture/Polyglot%20Cores.md).
-
-## Status
-
-- **Phase 0 — the agentic loop** (shipped): `IChatClient`-driven loop, `AIFunction` tools,
- usage accumulation, max-iteration guard, streaming. `MockChatClient` test double.
-- **Phase 1 — conversation + compaction** (shipped): `SmoothAgentThread` for multi-turn
- history, `MaxContextTokens` budget + `SlidingWindow` compaction.
-- **Phase 2 — memory + knowledge** (shipped): pluggable `IKnowledgeBase` / `IAgentMemory`,
- retrieved and injected as pre-turn grounding context (RAG).
-- **Phase 3 — checkpointing + resume** (shipped): `ICheckpointStore` + `CheckpointStrategy`;
- snapshot a run and `ResumeThreadAsync` to rebuild a thread after a crash.
-- **Phase 4 — HITL** (shipped): `IHumanGate` pauses for human approval before sensitive/write
- tools (`RequiresApproval`); a denial is fed back to the model and the tool never runs.
-- **Phase 5 — cast / subagents** (shipped): a lead delegates to clearance-scoped sidekicks via
- the `send_sidekick` tool (`Cast` / `OperatorRole` / `Clearance` / `SubagentDispatcher`);
- isolated transcripts, only the summary returns.
-- **Phase 6 — cost + budgets** (shipped): `CostTracker` (token + USD via `ModelPricing`) and
- `CostBudget` that halts a run at a spend/token ceiling (`AgentRunResponse.Cost` /
- `.BudgetExceeded`).
-- **Phase 7 — evals** (shipped): the five shared scenarios run against the live gateway + an
- LLM judge (aggregate mean ≥ 4.0), gated on `SMOOTH_AGENT_E2E=1` + `SMOOAI_GATEWAY_KEY`.
-
-**All phases shipped** — 31 parity tests + 1 gated live-eval suite. See the phased roadmap in
-the Polyglot Cores doc.
+
+ 
+
-```csharp
-// Multi-turn: pass a thread to each run and it remembers.
-var thread = agent.GetNewThread();
-await agent.RunAsync("My name is Brent.", thread);
-var r = await agent.RunAsync("What's my name?", thread); // "Your name is Brent."
-```
+
+ 
+ 
+ 
+
-```csharp
-// RAG: give it a knowledge base and it grounds answers in retrieved context.
-var kb = new InMemoryKnowledgeBase();
-await kb.IngestAsync(new KnowledgeDocument("returns", "The return window is 17 days.", "policy.md"));
+
+ 
+ 
+
+
+---
+
+> The C#/.NET 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 NuGet package. It's the engine, not a notebook demo.
+
+`SmooAI.SmoothOperator.Core` is the **native C# 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. Its API follows Microsoft.Extensions.AI naming.
-var agent = new SmoothAgent(model, new AgentOptions { Knowledge = kb });
-var r = await agent.RunAsync("How long is the return window?"); // grounded in policy.md
+It's a library, not a client to a remote server: it *is* the agent, running in your .NET process. Every surface is covered by **fast, offline tests** built on a deterministic `MockLlmProvider`, so the loop is verified — not vibe-coded.
+
+## Install
+
+```bash
+dotnet add package SmooAI.SmoothOperator.Core
```
## Quickstart
+A complete agent — no credentials needed — using the deterministic mock provider the engine's own tests run on:
+
```csharp
-using Microsoft.Extensions.AI;
using SmooAI.SmoothOperator.Core;
-// Any IChatClient — here, an OpenAI-compatible endpoint (the smooth gateway, Azure, …).
-IChatClient model = /* your MEAI client */;
+var provider = new MockLlmProvider().PushText("the answer is 42");
+var agent = new SmoothAgent(provider, new AgentOptions { Instructions = "You are a helpful assistant" });
-var options = new AgentOptions { Instructions = "You are a helpful support agent." };
-options.Tools.Add(AIFunctionFactory.Create(
- (string city) => $"The weather in {city} is sunny.",
- "get_weather", "Gets the weather for a city"));
+var response = await agent.RunAsync("what is the answer?");
+Console.WriteLine(response.Text);
+```
-var agent = new SmoothAgent(model, options);
+`new SmoothAgent(chatClient, options)` takes an `IChatClient` (the `MockLlmProvider` implements it — swap in any OpenAI-compatible client) and an `AgentOptions`. `await agent.RunAsync(...)` returns an `AgentRunResponse`; `response.Text` is the final assistant message.
-AgentRunResponse result = await agent.RunAsync("What's the weather in Chicago?");
-Console.WriteLine(result.Text); // final answer
-Console.WriteLine(result.Iterations); // LLM calls it took
-Console.WriteLine(result.Usage.TotalTokenCount);
-```
+## Features
-Stream it instead:
+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:
-```csharp
-await foreach (var update in agent.RunStreamingAsync("What's the weather in Chicago?"))
- Console.Write(update.Text);
-```
+- **Agentic tool-calling loop** — observe→think→act, looping until the model answers.
+- **Typed tools** — register tools the model can call, with parallel dispatch.
+- **Knowledge / RAG + vectors** — ground the turn in retrieved documents.
+- **Memory** — long-term entries recalled into context each turn.
+- **Compaction** — a sliding-window token budget keeps the prompt under a ceiling.
+- **Cost / budget** — per-model pricing, token + USD accounting, early stop on budget.
+- **Checkpointing** — persist/resume a conversation via a checkpoint store.
+- **Rerank** — rerank retrieved hits before injection (lexical reranker built in).
+- **Sub-agents / delegation** — spawn child agents for sub-tasks.
+- **Cast + clearance** — roles with per-role tool-access policy.
+- **Human-in-the-loop gate** — require approval before designated tool calls run.
+- **Conversation thread** — carry a conversation across multiple `RunAsync` calls.
+- **`LlmProvider` seam + `MockLlmProvider`** — inject any OpenAI-compatible client; the record/replay mock drives the offline tests.
+- **Deferred tools + `tool_search`** — hide rarely-used tool schemas behind a meta-tool the model calls to promote the ones it needs.
+- **Typed workflow graph** — a node/edge workflow engine alongside the agent loop.
+- **Parallel tool calls** — dispatch ≥2 tool calls concurrently (transcript order preserved).
+- **Retry / backoff** — retry transient model-call failures with exponential backoff.
+- **Streaming** — stream incremental text, tool calls, and tool results as the turn runs.
-## Build & test
+## Streaming
-```bash
-dotnet test dotnet/core/tests/SmooAI.SmoothOperator.Core.Tests.csproj
-# or the whole solution (client + core):
-dotnet test dotnet/SmooAI.SmoothOperator.slnx
-```
+`RunStreamingAsync` is the streaming variant of `RunAsync`: it yields incremental updates — text deltas as the model produces them, each tool call before dispatch, each tool result after it finishes, and a terminal update carrying the same response `RunAsync` would have returned.
+
+## Part of Smoo AI
+
+`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.
+
+- 🚀 **Smooth on the platform** — [smoo.ai/th](https://smoo.ai/th)
+- 🧰 **More open source from Smoo AI** — [smoo.ai/open-source](https://smoo.ai/open-source)
+- 🧩 **Run it hosted** — [lom.smoo.ai](https://lom.smoo.ai)
+
+## Links
+
+- [**lom.smoo.ai**](https://lom.smoo.ai) — run it hosted
+- [smooth-operator-core](https://github.com/SmooAI/smooth-operator-core) — the polyglot engine repo
+- [Polyglot Engines](https://github.com/SmooAI/smooth-operator-core/blob/main/docs/Polyglot-Engines.md) — install + hello-agent in all five languages
+- [smoo.ai](https://smoo.ai) — the product · [smoo.ai/open-source](https://smoo.ai/open-source) — more open source
+
+## License
+
+MIT — see [LICENSE](https://github.com/SmooAI/smooth-operator-core/blob/main/LICENSE).
-## Relationship to `SmooAI.SmoothOperator`
+---
-`SmooAI.SmoothOperator` (in `dotnet/src`) is the **protocol client** — it talks to a
-remote Rust `smooth-operator-server` over WebSocket, and exposes an `IChatClient` facade.
-`SmooAI.SmoothOperator.Core` (here) is the **engine** — it runs the agent locally. They're
-complementary: use the client to reach a hosted agent, use the core to *be* the agent.
+
+ Built by Smoo AI — AI built into every product.
+
diff --git a/go/core/README.md b/go/core/README.md
new file mode 100644
index 0000000..fce9be9
--- /dev/null
+++ b/go/core/README.md
@@ -0,0 +1,110 @@
+
+ 
+
+
+
+
+
+
+
+
+
+ 
+ 
+
+
+---
+
+> The Go 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 package. It's the engine, not a notebook demo.
+
+`github.com/SmooAI/smooth-operator-core/go/core` is the **native Go 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.
+
+It's a library, not a client to a remote server: it *is* the agent, running in your Go process. Every surface is covered by **fast, offline tests** built on a deterministic `MockLlmProvider`, so the loop is verified — not vibe-coded.
+
+## Install
+
+```bash
+go get github.com/SmooAI/smooth-operator-core/go/core
+```
+
+The engine is the `core` package; idiomatic alias `core`.
+
+## Quickstart
+
+A complete agent — no credentials needed — using the deterministic mock provider the engine's own tests run on:
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+
+ core "github.com/SmooAI/smooth-operator-core/go/core"
+)
+
+func main() {
+ provider := core.NewMockLlmProvider().PushText("the answer is 42")
+ agent := core.NewSmoothAgent(provider, core.AgentOptions{Instructions: "You are a helpful assistant"})
+
+ res, err := agent.Run(context.Background(), "what is the answer?", nil)
+ if err != nil {
+ panic(err)
+ }
+ fmt.Println(res.Text)
+}
+```
+
+`NewSmoothAgent(client, options)` takes a `ChatClient` (the `MockLlmProvider` implements it — swap in any OpenAI-compatible client) and an `AgentOptions` struct. `Run(ctx, message, history)` — pass `nil` history for a fresh turn — returns `(AgentRunResponse, error)`; `res.Text` is the final answer.
+
+## Features
+
+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:
+
+- **Agentic tool-calling loop** — observe→think→act, looping until the model answers.
+- **Typed tools** — register tools the model can call, with parallel dispatch.
+- **Knowledge / RAG + vectors** — ground the turn in retrieved documents.
+- **Memory** — long-term entries recalled into context each turn.
+- **Compaction** — a sliding-window token budget keeps the prompt under a ceiling.
+- **Cost / budget** — per-model pricing, token + USD accounting, early stop on budget.
+- **Checkpointing** — persist/resume a conversation via a checkpoint store.
+- **Rerank** — rerank retrieved hits before injection (lexical reranker built in).
+- **Sub-agents / delegation** — spawn child agents for sub-tasks.
+- **Cast + clearance** — roles with per-role tool-access policy.
+- **Human-in-the-loop gate** — require approval before designated tool calls run.
+- **Conversation thread** — carry a conversation across multiple `Run` calls.
+- **`LlmProvider` seam + `MockLlmProvider`** — inject any OpenAI-compatible client; the record/replay mock drives the offline tests.
+- **Deferred tools + `tool_search`** — hide rarely-used tool schemas behind a meta-tool the model calls to promote the ones it needs.
+- **Typed workflow graph** — a generic `Workflow[S]` node/edge engine alongside the agent loop.
+- **Parallel tool calls** — dispatch ≥2 tool calls concurrently (transcript order preserved).
+- **Retry / backoff** — retry transient model-call failures with exponential backoff.
+- **Streaming** — stream incremental text, tool calls, and tool results as the turn runs.
+
+## Streaming
+
+`RunStream` is the streaming variant of `Run`: it yields incremental events — `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.
+
+## Part of Smoo AI
+
+`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.
+
+- 🚀 **Smooth on the platform** — [smoo.ai/th](https://smoo.ai/th)
+- 🧰 **More open source from Smoo AI** — [smoo.ai/open-source](https://smoo.ai/open-source)
+- 🧩 **Run it hosted** — [lom.smoo.ai](https://lom.smoo.ai)
+
+## Links
+
+- [**lom.smoo.ai**](https://lom.smoo.ai) — run it hosted
+- [smooth-operator-core](https://github.com/SmooAI/smooth-operator-core) — the polyglot engine repo
+- [Polyglot Engines](https://github.com/SmooAI/smooth-operator-core/blob/main/docs/Polyglot-Engines.md) — install + hello-agent in all five languages
+- [smoo.ai](https://smoo.ai) — the product · [smoo.ai/open-source](https://smoo.ai/open-source) — more open source
+
+## License
+
+MIT — see [LICENSE](https://github.com/SmooAI/smooth-operator-core/blob/main/LICENSE).
+
+---
+
+
+ Built by Smoo AI — AI built into every product.
+
diff --git a/python/core/README.md b/python/core/README.md
index d0f5da8..d27a72f 100644
--- a/python/core/README.md
+++ b/python/core/README.md
@@ -1 +1,111 @@
-# smooth-operator-core (Python)
+
+ 
+
+
+
+
+
+
+
+
+
+ 
+ 
+
+
+---
+
+> The Python 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 package. It's the engine, not a notebook demo.
+
+`smooai-smooth-operator-core` is the **native Python 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.
+
+It's a library, not a client to a remote server: it *is* the agent, running in your Python process. Every surface is covered by **fast, offline tests** built on a deterministic `MockLlmProvider`, so the loop is verified — not vibe-coded.
+
+## Install
+
+```bash
+pip install smooai-smooth-operator-core
+```
+
+Import as `smooth_operator_core`.
+
+## Quickstart
+
+A complete agent — no credentials needed — using the deterministic mock provider the engine's own tests run on:
+
+```python
+import asyncio
+from smooth_operator_core import SmoothAgent, AgentOptions, MockLlmProvider
+
+async def main():
+ provider = MockLlmProvider()
+ provider.push_text("the answer is 42")
+
+ agent = SmoothAgent(provider, AgentOptions(instructions="You are a helpful assistant"))
+ result = await agent.run("what is the answer?")
+ print(result.text)
+
+asyncio.run(main())
+```
+
+`SmoothAgent(chat_client, options)` takes the provider (the `MockLlmProvider` — swap in any OpenAI-compatible client) and an `AgentOptions` dataclass (all fields default, so `AgentOptions()` is valid). `await agent.run(...)` returns an `AgentRunResponse`; `result.text` is the final answer.
+
+## Features
+
+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:
+
+- **Agentic tool-calling loop** — observe→think→act, looping until the model answers.
+- **Typed tools** — register tools the model can call, with parallel dispatch.
+- **Knowledge / RAG + vectors** — ground the turn in retrieved documents.
+- **Memory** — long-term entries recalled into context each turn.
+- **Compaction** — a sliding-window token budget keeps the prompt under a ceiling.
+- **Cost / budget** — per-model pricing, token + USD accounting, early stop on budget.
+- **Checkpointing** — persist/resume a conversation via a checkpoint store.
+- **Rerank** — rerank retrieved hits before injection (lexical reranker built in).
+- **Sub-agents / delegation** — spawn child agents for sub-tasks.
+- **Cast + clearance** — roles with per-role tool-access policy.
+- **Human-in-the-loop gate** — require approval before designated tool calls run.
+- **Conversation thread** — `SmoothAgentThread` carries a conversation across multiple `run` calls.
+- **`LlmProvider` seam + `MockLlmProvider`** — inject any OpenAI-compatible client; the record/replay mock drives the offline tests.
+- **Deferred tools + `tool_search`** — hide rarely-used tool schemas behind a meta-tool the model calls to promote the ones it needs.
+- **Typed workflow graph** — a node/edge workflow engine alongside the agent loop.
+- **Parallel tool calls** — dispatch ≥2 tool calls concurrently (transcript order preserved).
+- **Retry / backoff** — retry transient model-call failures with exponential backoff.
+- **Streaming** — stream incremental text, tool calls, and tool results as the turn runs.
+
+## Streaming
+
+`run_stream` is the async streaming variant of `run`: it yields incremental events — `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.
+
+```python
+async for event in agent.run_stream("what is the answer?"):
+ if event.type == "text":
+ print(event.text, end="")
+ elif event.type == "done":
+ print(f"\n{event.response.text}")
+```
+
+## Part of Smoo AI
+
+`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.
+
+- 🚀 **Smooth on the platform** — [smoo.ai/th](https://smoo.ai/th)
+- 🧰 **More open source from Smoo AI** — [smoo.ai/open-source](https://smoo.ai/open-source)
+- 🧩 **Run it hosted** — [lom.smoo.ai](https://lom.smoo.ai)
+
+## Links
+
+- [**lom.smoo.ai**](https://lom.smoo.ai) — run it hosted
+- [smooth-operator-core](https://github.com/SmooAI/smooth-operator-core) — the polyglot engine repo
+- [Polyglot Engines](https://github.com/SmooAI/smooth-operator-core/blob/main/docs/Polyglot-Engines.md) — install + hello-agent in all five languages
+- [smoo.ai](https://smoo.ai) — the product · [smoo.ai/open-source](https://smoo.ai/open-source) — more open source
+
+## License
+
+MIT — see [LICENSE](https://github.com/SmooAI/smooth-operator-core/blob/main/LICENSE).
+
+---
+
+
+ Built by Smoo AI — AI built into every product.
+
diff --git a/rust/smooth-operator-core/README.md b/rust/smooth-operator-core/README.md
index 58162da..29ff1cf 100644
--- a/rust/smooth-operator-core/README.md
+++ b/rust/smooth-operator-core/README.md
@@ -1,82 +1,110 @@
-# smooth-operator-core
+
+ 
+
-Rust-native AI agent framework with built-in checkpointing, tool system, and LLM client. Purpose-built for orchestrated agent workloads with security-first design.
+
+
+
+
+
-## Features
+
+ 
+ 
+
-- **LLM Client** -- OpenAI-compatible and Anthropic API support with streaming, retry policies, and rate limit handling
-- **Tool System** -- Trait-based tools with pre/post hooks for surveillance, secret detection, and prompt injection guards
-- **Agent Loop** -- Observe-think-act cycle with configurable iteration limits, parallel tool execution, and cost budgets
-- **Checkpointing** -- Pluggable checkpoint stores for session resume and fault tolerance
-- **Conversation Management** -- Token-aware context window with compaction strategies
-- **Memory & Knowledge** -- Trait-based memory and knowledge base integration
-- **Cost Tracking** -- Per-model pricing, token budgets, and budget enforcement
+---
-## Quick Start
+> The agent runtime behind the [smooth-operator](https://github.com/SmooAI/smooth-operator) service and [lom.smoo.ai](https://lom.smoo.ai). Agents, workflows, tools, checkpointing, memory, human-in-the-loop, and per-model cost budgets — as a single embeddable Rust crate. It's the engine, not a notebook demo.
-```rust
-use smooth_operator_core::{Agent, AgentConfig, LlmConfig, Tool, ToolRegistry, ToolSchema};
-use async_trait::async_trait;
-
-// Define a tool
-struct GetWeather;
-
-#[async_trait]
-impl Tool for GetWeather {
- fn schema(&self) -> ToolSchema {
- ToolSchema {
- name: "get_weather".into(),
- description: "Get current weather for a city".into(),
- parameters: serde_json::json!({
- "type": "object",
- "properties": {
- "city": { "type": "string", "description": "City name" }
- },
- "required": ["city"]
- }),
- }
- }
-
- async fn execute(&self, args: serde_json::Value) -> anyhow::Result {
- let city = args["city"].as_str().unwrap_or("unknown");
- Ok(format!("Weather in {city}: 72F, sunny"))
- }
-}
+`smooai-smooth-operator-core` is the **reference implementation** of the Smoo AI agent engine — the observe→think→act loop that powers the [**smooth-operator**](https://github.com/SmooAI/smooth-operator) service and [**lom.smoo.ai**](https://lom.smoo.ai). It gives you the moving parts of a serious agent framework — a typed tool system, a graph workflow engine, pluggable checkpoint stores, memory, RAG, human-in-the-loop gates, and per-model cost budgets — as one embeddable crate.
-#[tokio::main]
-async fn main() -> anyhow::Result<()> {
- // Configure LLM
- let llm = LlmConfig {
- api_url: "https://api.openai.com/v1".into(),
- api_key: std::env::var("OPENAI_API_KEY")?,
- model: "gpt-4o".into(),
- ..Default::default()
- };
+This Rust crate is the source of truth: the [TypeScript, Python, Go, and C#/.NET engines](https://github.com/SmooAI/smooth-operator-core/blob/main/docs/Polyglot-Engines.md) mirror its behavior. Every surface is covered by **fast, offline unit tests** built on a deterministic `MockLlmClient`, so the loop is verified — not vibe-coded.
+
+## Install
+
+```bash
+cargo add smooai-smooth-operator-core
+cargo add tokio --features full
+cargo add anyhow
+```
- // Build agent with tools
- let config = AgentConfig::new("assistant", "You are a helpful assistant.", llm)
- .with_max_iterations(10)
- .with_parallel_tools(true);
+The crate is `smooai-smooth-operator-core` (library `smooth_operator_core`), v0.14.0.
- let mut registry = ToolRegistry::new();
- registry.register(GetWeather);
+## Quickstart
- let mut agent = Agent::new(config, registry);
- let events = agent.run("What's the weather in Tokyo?").await?;
+A complete agent — no credentials needed — using the deterministic mock provider the engine's own tests run on:
- for event in events {
- println!("{event:?}");
- }
+```rust
+use std::sync::Arc;
+use smooth_operator_core::{Agent, AgentConfig, LlmConfig, ToolRegistry};
+use smooth_operator_core::llm_provider::MockLlmClient;
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+ let mock = MockLlmClient::new();
+ mock.push_text("the answer is 42");
+
+ let config = AgentConfig::new("agent", "You are a helpful assistant", LlmConfig::openrouter("fake-key"));
+ let agent = Agent::new(config, ToolRegistry::new())
+ .with_llm_provider(Arc::new(mock.clone()));
+
+ let conversation = agent.run("what is the answer?").await?;
+ println!("{}", conversation.last_assistant_content().unwrap_or(""));
Ok(())
}
```
-## License
+`with_llm_provider` injects any `Arc` (here the mock); without it, `run` builds a real OpenAI-compatible `LlmClient` from `config.llm` — point `LlmConfig.api_url` at OpenAI, an Anthropic-compatible proxy, vLLM, Ollama's shim, or your own gateway (`https://llm.smoo.ai/v1`). `run` returns the full `Conversation`; `last_assistant_content()` is the final answer.
-MIT
+## Features
+
+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, and this crate defines it:
+
+- **Agentic tool-calling loop** — observe→think→act with iteration caps and a typed `AgentEvent` stream.
+- **Typed tools + guardrails** — `Tool` trait + `ToolRegistry`, with pre/post hooks for surveillance, secret detection, and prompt-injection guards.
+- **Knowledge / RAG + vectors** — `KnowledgeBase` trait grounds each turn in retrieved documents.
+- **Memory** — long-term entries recalled into context each turn.
+- **Compaction** — a sliding-window token budget keeps the prompt under a ceiling.
+- **Cost / budget** — per-model `ModelPricing`, `CostBudget`, `CostTracker` with hard enforcement.
+- **Checkpointing** — `CheckpointStore`: in-memory, SQLite (`sqlite` feature), or Postgres (`postgres` feature) for resume.
+- **Rerank** — rerank retrieved hits before injection (lexical reranker built in).
+- **Sub-agents / delegation** — spawn child agents for sub-tasks.
+- **Cast + clearance** — roles with per-role tool-access policy.
+- **Human-in-the-loop gate** — `ConfirmationHook` requires approval before designated tool calls run.
+- **Conversation thread** — carry a conversation across multiple `run` calls.
+- **`LlmProvider` seam + `MockLlmClient`** — inject any OpenAI-compatible client; the record/replay mock drives the offline tests.
+- **Deferred tools + `tool_search`** — hide rarely-used tool schemas behind a built-in meta-tool the model calls to promote the ones it needs.
+- **Typed workflow graph** — `Workflow` / `WorkflowBuilder` with conditional edges and typed state.
+- **Parallel tool calls** — dispatch ≥2 tool calls concurrently (transcript order preserved).
+- **Retry / backoff** — retry transient model-call failures with exponential backoff.
+- **Streaming** — incremental text, tool calls, and tool results as the turn runs.
+
+## Streaming
+
+For live token deltas, tool-call, and tool-result events, drive the agent with `run_with_channel(msg, tx)` and consume the `AgentEvent` stream off the receiver — instead of `run`, which returns a single completed `Conversation`.
+
+## Part of Smoo AI
+
+`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.
+
+- 🚀 **Smooth on the platform** — [smoo.ai/th](https://smoo.ai/th)
+- 🧰 **More open source from Smoo AI** — [smoo.ai/open-source](https://smoo.ai/open-source)
+- 🧩 **Run it hosted** — [lom.smoo.ai](https://lom.smoo.ai)
## Links
-- [GitHub](https://github.com/SmooAI/smooth)
-- [crates.io](https://crates.io/crates/smooth-operator-core)
+- [**lom.smoo.ai**](https://lom.smoo.ai) — run it hosted
+- [smooth-operator-core](https://github.com/SmooAI/smooth-operator-core) — the polyglot engine repo
+- [Polyglot Engines](https://github.com/SmooAI/smooth-operator-core/blob/main/docs/Polyglot-Engines.md) — install + hello-agent in all five languages
+- [smoo.ai](https://smoo.ai) — the product · [smoo.ai/open-source](https://smoo.ai/open-source) — more open source
+
+## License
+
+MIT — see [LICENSE](https://github.com/SmooAI/smooth-operator-core/blob/main/LICENSE).
+
+---
+
+
+ Built by Smoo AI — AI built into every product.
+
diff --git a/typescript/core/README.md b/typescript/core/README.md
new file mode 100644
index 0000000..b896e4a
--- /dev/null
+++ b/typescript/core/README.md
@@ -0,0 +1,105 @@
+
+ 
+
+
+
+
+
+
+
+
+
+ 
+ 
+
+
+---
+
+> 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.
+
+`@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.
+
+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.
+
+## Install
+
+```bash
+npm install @smooai/smooth-operator-core
+```
+
+## Quickstart
+
+A complete agent — no credentials needed — using the deterministic mock provider the engine's own tests run on:
+
+```ts
+import { SmoothAgent, MockLlmProvider } from '@smooai/smooth-operator-core';
+
+const provider = new MockLlmProvider().pushText('the answer is 42');
+const agent = new SmoothAgent(provider, { instructions: 'You are a helpful assistant' });
+
+const response = await agent.run('what is the answer?');
+console.log(response.text);
+```
+
+`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.
+
+## Features
+
+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:
+
+- **Agentic tool-calling loop** — observe→think→act, looping until the model answers.
+- **Typed tools** — register `Tool`s the model can call, with parallel dispatch.
+- **Knowledge / RAG + vectors** — `InMemoryKnowledge` / `VectorKnowledge` ground the turn in retrieved documents.
+- **Memory** — `InMemoryMemory` recalls long-term entries into context each turn.
+- **Compaction** — a sliding-window token budget keeps the prompt under a ceiling.
+- **Cost / budget** — `CostTracker` + `CostBudget` with per-model pricing and early stop.
+- **Checkpointing** — `InMemoryCheckpointStore` (and the `CheckpointStore` seam) persist/resume a conversation.
+- **Rerank** — `LexicalReranker` reranks retrieved hits before injection.
+- **Sub-agents / delegation** — `delegateTool` spawns child agents for sub-tasks.
+- **Cast + clearance** — `Cast`, `Clearance`, `makeRole` for per-role tool-access policy.
+- **Human-in-the-loop gate** — `HumanGate` requires approval before designated tool calls run.
+- **Conversation thread** — `SmoothAgentThread` carries a conversation across multiple `run` calls.
+- **`LlmProvider` seam + `MockLlmProvider`** — inject any OpenAI-compatible client; the record/replay mock drives the offline tests.
+- **Deferred tools + `tool_search`** — `ToolSearch` hides rarely-used tool schemas behind a meta-tool the model calls to promote the ones it needs.
+- **Typed workflow graph** — `Workflow` with typed nodes/edges, alongside the agent loop.
+- **Parallel tool calls** — dispatch ≥2 tool calls concurrently (transcript order preserved).
+- **Retry / backoff** — retry transient model-call failures with exponential backoff.
+- **Streaming** — stream incremental text, tool calls, and tool results as the turn runs.
+
+## Streaming
+
+`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.
+
+```ts
+for await (const event of agent.runStream('what is the answer?')) {
+ if (event.type === 'text') process.stdout.write(event.text);
+ if (event.type === 'done') console.log(`\n${event.response.text}`);
+}
+```
+
+`runStream` requires a streaming-capable client (`chat.completions.createStream`); the `MockLlmProvider` supplies one, replaying the same script as the non-streaming path.
+
+## Part of Smoo AI
+
+`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.
+
+- 🚀 **Smooth on the platform** — [smoo.ai/th](https://smoo.ai/th)
+- 🧰 **More open source from Smoo AI** — [smoo.ai/open-source](https://smoo.ai/open-source)
+- 🧩 **Run it hosted** — [lom.smoo.ai](https://lom.smoo.ai)
+
+## Links
+
+- [**lom.smoo.ai**](https://lom.smoo.ai) — run it hosted
+- [smooth-operator-core](https://github.com/SmooAI/smooth-operator-core) — the polyglot engine repo
+- [Polyglot Engines](https://github.com/SmooAI/smooth-operator-core/blob/main/docs/Polyglot-Engines.md) — install + hello-agent in all five languages
+- [smoo.ai](https://smoo.ai) — the product · [smoo.ai/open-source](https://smoo.ai/open-source) — more open source
+
+## License
+
+MIT — see [LICENSE](https://github.com/SmooAI/smooth-operator-core/blob/main/LICENSE).
+
+---
+
+
+ Built by Smoo AI — AI built into every product.
+