docs: branded, on-brand READMEs for all 5 published packages

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.
+<p align="center">
+  <a href="https://smoo.ai"><img src="https://raw.githubusercontent.com/SmooAI/smooth-operator-core/main/.github/banner-dotnet.png" alt="smooth-operator-core — The C# / .NET engine for orchestrated AI agents" width="100%" /></a>
+</p>
 
-```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."
-```
+<p align="center">
+  <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>
+  <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>
+  <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>
+</p>
 
-```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"));
+<p align="center">
+  <a href="https://www.nuget.org/packages/SmooAI.SmoothOperator.Core"><img src="https://img.shields.io/nuget/v/SmooAI.SmoothOperator.Core?style=flat-square&color=00A6A6&labelColor=020618" alt="NuGet"></a>
+  <img src="https://img.shields.io/badge/.NET-engine-512BD4?style=flat-square&labelColor=020618" alt=".NET engine">
+</p>
+
+---
+
+> 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.
+<p align="center">
+  Built by <a href="https://smoo.ai"><strong>Smoo AI</strong></a> — AI built into every product.
+</p>

go/core/README.md

@@ -0,0 +1,110 @@
+<p align="center">
+  <a href="https://smoo.ai"><img src="https://raw.githubusercontent.com/SmooAI/smooth-operator-core/main/.github/banner-go.png" alt="smooth-operator-core — The Go engine for orchestrated AI agents" width="100%" /></a>
+</p>
+
+<p align="center">
+  <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>
+  <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>
+  <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>
+</p>
+
+<p align="center">
+  <a href="https://pkg.go.dev/github.com/SmooAI/smooth-operator-core/go/core"><img src="https://img.shields.io/badge/pkg.go.dev-reference-00ADD8?style=flat-square&labelColor=020618" alt="pkg.go.dev"></a>
+  <img src="https://img.shields.io/badge/Go-engine-00ADD8?style=flat-square&labelColor=020618" alt="Go engine">
+</p>
+
+---
+
+> 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).
+
+---
+
+<p align="center">
+  Built by <a href="https://smoo.ai"><strong>Smoo AI</strong></a> — AI built into every product.
+</p>