diff --git a/README.md b/README.md index 3aa1f72..76802c0 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,66 @@

- Smooth + Smoo AI +

+ +

@smooai/deploy

+ +

+ Deploy a smooth-operator agent two ways from one package — SST v4 constructs for AWS serverless, and a Helm chart + ArgoCD for Kubernetes.

- Deploy a smooth-operator agent two ways, from one package.
- Reusable SST v4 constructs for AWS serverless, and a Helm chart + ArgoCD for Kubernetes — the shared deploy primitives behind smooth-operator, dogfooded by smooai. + Smoo AI + license + TypeScript / SST v4 + Helm + ArgoCD + lom.smoo.ai

- MIT License - tsc + helm lint passing - SST v4 constructs - Helm + ArgoCD - lom.smoo.ai + Features · + Install · + Usage · + Platform

--- -`@smooai/deploy` packages the **deploy primitives** for a [smooth-operator](https://github.com/SmooAI/smooth-operator)-style agent so you don't hand-roll them per service. It gives you two production-shaped paths off the same conventions: +> `@smooai/deploy` packages the deploy primitives for a [smooth-operator](https://github.com/SmooAI/smooth-operator)-style agent so you don't hand-roll them per service. The same agent ships to AWS serverless or Kubernetes off one set of conventions — you pick the runtime, not the agent. + +It gives you two production-shaped paths off the same conventions: - **AWS serverless** — `new SmoothAgentApi(...)`: an API Gateway WebSocket + (Rust) Lambda + DynamoDB single table + S3 blob bucket + S3 Vectors wiring + gateway-key secret + IAM links, as a single parameterized SST component. - **Kubernetes / self-host** — the `smooth-operator` Helm chart: an axum `/ws` server backed by pgvector Postgres, fronted by a WebSocket-friendly Ingress, synced by ArgoCD. Two real consumers justify the shared package: **smooth-operator** (the reference WebSocket agent service, uses both surfaces today) and the **smooai monorepo** (dogfoods the SST constructs piecemeal). ---- +## ✨ Features + +| You want… | `@smooai/deploy` gives you | +| --- | --- | +| **One construct**, whole serverless backend | `SmoothAgentApi`: WS API + Lambda + Dynamo + S3 + Vectors + secret + IAM | +| **Composable** primitives | `WebSocketLambdaApi`, `DynamoSingleTable` exported independently | +| **A Kubernetes path too** | the `smooth-operator` Helm chart + ArgoCD `Application` | +| **No copy-paste between services** | the smooth-operator deploy logic, extracted and parameterized | +| **Safe-by-default pods** | non-root, read-only rootfs, dropped caps, seccomp `RuntimeDefault` | +| **WebSocket-aware Ingress** | long proxy timeouts + websocket annotations baked into chart defaults | -## Quickstart +## 📦 Install + +`@smooai/deploy` is consumed today via a **path dep** for local development: + +```jsonc +// package.json +{ + "dependencies": { + "@smooai/deploy": "file:../../deploy/sst" + } +} +``` + +> **Publishing follow-up:** publish `@smooai/deploy` to npm (and the chart to an OCI/HTTP Helm repo) so consumers pin a version instead of a sibling-checkout path. See [`docs/Consuming.md`](docs/Consuming.md). + +## 🚀 Usage ### AWS serverless — one construct in your `sst.config.ts` @@ -59,9 +93,7 @@ helm upgrade --install smooth-operator helm/smooth-operator \ > Postgres with the **pgvector** extension is an external dependency (the chart does not vendor a Postgres pod). Point `database.urlSecretRef` at a pgvector-enabled database — see [`helm/smooth-operator/README.md`](helm/smooth-operator/README.md). ---- - -## Showcase: compose the smaller primitives +### Compose the smaller primitives `SmoothAgentApi` is the batteries-included path. When you want to assemble your own topology, the sub-constructs are first-class: @@ -83,22 +115,7 @@ const { api } = WebSocketLambdaApi('AgentApi', { Defaults are sensible: the WebSocket route table covers `$connect`, `$disconnect`, `send_message`, `ping`, and `$default`; the gateway URL defaults to `https://llm.smoo.ai/v1`; the model defaults to `claude-haiku-4-5`. ---- - -## Why this - -| You want… | @smooai/deploy gives you | -| --- | --- | -| **One construct**, whole serverless backend | `SmoothAgentApi`: WS API + Lambda + Dynamo + S3 + Vectors + secret + IAM | -| **Composable** primitives | `WebSocketLambdaApi`, `DynamoSingleTable` exported independently | -| **A Kubernetes path too** | the `smooth-operator` Helm chart + ArgoCD `Application` | -| **No copy-paste between services** | the smooth-operator deploy logic, extracted and parameterized | -| **Safe-by-default pods** | non-root, read-only rootfs, dropped caps, seccomp `RuntimeDefault` | -| **WebSocket-aware Ingress** | long proxy timeouts + websocket annotations baked into chart defaults | - ---- - -## Architecture — one agent, two deploy paths +## 📖 Architecture — one agent, two deploy paths ```mermaid flowchart TB @@ -136,11 +153,9 @@ flowchart TB The same agent ships as a Lambda artifact (serverless) or a container image (k8s). Both speak the same WebSocket protocol and call the same OpenAI-compatible LLM gateway — you pick the runtime, not the agent. ---- - -## Test-driven by default — verified, not vibe-coded +## 📖 Verified, not vibe-coded -Infra you can't `cargo test` still has to be **verified, not vibe-coded**. This package proves correctness without a live AWS account or cluster: +Infra you can't `cargo test` still has to be verified. This package proves correctness without a live AWS account or cluster: - **SST constructs** typecheck against real SST platform types: `pnpm sst install` generates `.sst/platform`, then `tsc --noEmit` validates the constructs compile against the SDK surface — catching the SST footguns (unlinked resources, ambient-global misuse) that only `next build`-class checks surface. - **Helm chart** is linted and rendered: `helm lint` + `helm template` validate the chart and ArgoCD `Application` produce valid manifests. @@ -175,9 +190,7 @@ helm template smooth-operator helm/smooth-operator > The full quality pyramid spans repos: the engine's **408 unit tests + LLM-as-judge evals** (which caught a multi-turn defect that scored 1/5 → fixed → 5/5) and the widget's **live Playwright e2e** sit above this package's static + smoke verification. ---- - -## Constructs reference +## 📖 Constructs reference | Export | What it is | | --- | --- | @@ -198,9 +211,7 @@ helm template smooth-operator helm/smooth-operator > **The S3 Vectors gap:** SST v4 ships no native S3 Vectors component (the service went GA 2025-12). `SmoothAgentApi` declares the intended bucket/index names, wires them into the Lambda env, and grants `s3vectors:*` — but does not create the vector bucket/index as a first-class resource by default. Provision it out-of-band per the README until your AWS provider exposes `aws.s3vectors.*`. ---- - -## Helm chart (`smooth-operator`) +## 📖 Helm chart (`smooth-operator`) ```bash helm lint helm/smooth-operator @@ -214,30 +225,32 @@ helm template smooth-operator helm/smooth-operator See [`helm/smooth-operator/README.md`](helm/smooth-operator/README.md) for the pgvector requirement, secret wiring, Ingress notes, and ArgoCD. ---- - -## Smoo-powered or bring-your-own +## 📖 Smoo-powered or bring-your-own **Bring-your-own:** deploy into *your* AWS account (SST) or *your* cluster (Helm/ArgoCD). Point the gateway URL at any OpenAI-compatible endpoint, bring your own pgvector Postgres or provision the S3 Vectors index yourself. You own the infra end to end. **Smoo-powered:** point the gateway at `https://llm.smoo.ai/v1` for unified billing + model routing, or skip the deploy entirely and let [**lom.smoo.ai**](https://lom.smoo.ai) run the smooth-operator service for you. ---- - -## Publishing follow-up +## 🧩 Part of Smoo AI {#part-of-smoo-ai} -`@smooai/deploy` is consumed today via a **path dep** (`"@smooai/deploy": "file:../../deploy/sst"`) for local development. The follow-up is to **publish `@smooai/deploy` to npm** (and the chart to an OCI/HTTP Helm repo) so consumers pin a version instead of a sibling-checkout path. See [`docs/Consuming.md`](docs/Consuming.md). - ---- +`@smooai/deploy` is part of the [Smoo AI](https://smoo.ai) platform — an AI-powered business platform with AI built into every product. It packages the deploy primitives behind the rest of the stack: -## Links - -- [**lom.smoo.ai**](https://lom.smoo.ai) — hosted agent service - [smooth-operator](https://github.com/SmooAI/smooth-operator) — the agent service this deploys - [smooth-operator-core](https://github.com/SmooAI/smooth-operator-core) — the Rust engine +- [smooth](https://github.com/SmooAI/smooth) — the Smoo AI CLI (`th`) and orchestration platform - [chat-widget](https://github.com/SmooAI/chat-widget) — the embeddable widget -- [smoo.ai](https://smoo.ai) — the product · [github.com/SmooAI](https://github.com/SmooAI) — more open source +- [**lom.smoo.ai**](https://lom.smoo.ai) — hosted agent service -## License +## 🤝 Contributing + +Issues and PRs welcome. Keep deploys in CI — never deploy locally. + +## 📄 License [MIT](LICENSE) © Smoo AI. + +--- + +

+ Built by Smoo AI — AI built into every product. +