{"id":49567560,"url":"https://github.com/codex-mohan/spectra","last_synced_at":"2026-06-05T16:00:43.455Z","repository":{"id":350435528,"uuid":"1205088279","full_name":"codex-mohan/spectra","owner":"codex-mohan","description":"A fast and minimal agent library for typescript and rust","archived":false,"fork":false,"pushed_at":"2026-05-28T20:56:55.000Z","size":7927,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T22:23:06.246Z","etag":null,"topics":["agent-cli","agent-cli-framework","agents","agents-sdk","ai-agents","coding-agent","llm","llm-agent","orchestration","rust","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codex-mohan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-08T16:13:14.000Z","updated_at":"2026-05-28T20:56:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/codex-mohan/spectra","commit_stats":null,"previous_names":["codex-mohan/spectra"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/codex-mohan/spectra","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codex-mohan%2Fspectra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codex-mohan%2Fspectra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codex-mohan%2Fspectra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codex-mohan%2Fspectra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codex-mohan","download_url":"https://codeload.github.com/codex-mohan/spectra/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codex-mohan%2Fspectra/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33949039,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-cli","agent-cli-framework","agents","agents-sdk","ai-agents","coding-agent","llm","llm-agent","orchestration","rust","typescript"],"created_at":"2026-05-03T12:05:52.939Z","updated_at":"2026-06-05T16:00:43.448Z","avatar_url":"https://github.com/codex-mohan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/assets/spectra-banner.png\" alt=\"Spectra Banner\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n# Spectra\n\n**Minimal, ultra-fast, multi-language AI agent framework**\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-0.2.4-3178C6?style=for-the-badge\u0026logo=typescript\u0026logoColor=white\u0026labelColor=0D0D0D)](https://www.typescriptlang.org)\n[![Rust](https://img.shields.io/badge/Rust-1.75+-000000?style=for-the-badge\u0026logo=rust\u0026logoColor=white\u0026labelColor=0D0D0D)](https://www.rust-lang.org)\n[![License](https://img.shields.io/badge/License-MIT-00B140?style=for-the-badge\u0026labelColor=0D0D0D)](LICENSE)\n\n---\n\nA construction kit, not a pre-built house — ship only primitives that enable developers to build anything beyond the core without fighting the framework.\n\nEach SDK (TypeScript, Rust) is a **complete, independent native implementation** — same API surface, same behavior, no shared runtime, no bindings, no FFI.\n\n## Why Spectra?\n\nI built Spectra because I lost months debugging framework bugs instead of building my product.\n\nEvery agent framework I tried — **LangChain, LangGraph**, and others — followed the same pattern: endless layers of abstraction for things that are, at their core, just a simple loop. An agent takes input, calls a model, processes the response, dispatches tools, and repeats. That's it. A loop. Everything else — the chains, graphs, runnables, callbacks, tracing hooks, and configurable-everything — is just over-engineering dressed up as architecture.\n\nThe cost of this over-engineering is real. I spent weeks tracking down bugs that turned out to be SDK issues, not application logic. Deployment options were limited. And worst of all, these frameworks create **vendor lock-in** — your entire codebase becomes coupled to abstractions you didn't need in the first place.\n\n**Spectra takes the opposite approach.** No graphs. No chains. No runtime that owns your application. Just the primitives — a loop, a model call, a tool dispatch, a stream — that you assemble however you need. If you can write a `for` loop, you can understand the entire framework in 10 minutes.\n\n**Built for hackers who just want things to work. Ship what you mean, not what the framework lets you.**\n\n### \"But Spectra has rate limiters, circuit breakers, session stores...\"\n\nThere's a difference between **abstractions you don't need** and **utilities everyone ends up building anyway.** LangChain invents chains, graphs, and runnables you never asked for. Rate limiting, circuit breakers, session persistence, SSE bridging — those aren't architecture opinions. They're infrastructure you'd write by hand in every production app. Spectra ships them as composable primitives so you don't spend 3 weeks building the same boilerplate every time.\n\nThink of Spectra as two layers: a **lean core** (agent loop + tools + streaming) and a **utility belt** (rate limiting, session stores, health probes) — use what you need, ignore what you don't. The core never forces the belt on you.\n\n## Architecture\n\n```mermaid\ngraph TB\n    subgraph TypeScript[\"TypeScript SDK — @mohanscodex/*\"]\n        AI[\"spectra-ai\u003cbr/\u003eLLM Providers\"]\n        AGENT[\"spectra-agent\u003cbr/\u003eAgent Loop + Tools\"]\n        APP[\"spectra-app\u003cbr/\u003eSessionEngine + Rate Limiting + SSE Bridge\"]\n        AI --\u003e AGENT --\u003e APP\n    end\n\n    subgraph Rust[\"Rust SDK — spectra-*\"]\n        RS[\"spectra-rs\u003cbr/\u003eCore Types + Agent + Events\"]\n        HTTP[\"spectra-http\u003cbr/\u003eAnthropic + OpenAI + Groq\"]\n        RS --\u003e HTTP\n    end\n\n    subgraph Deploy[\"Deployment Scale\"]\n        LOCAL[\"Local · SQLite\u003cbr/\u003ecoding agent, REPL\"]\n        SERVER[\"Server · Redis + SSE\u003cbr/\u003eSaaS, single-node\"]\n        CLUSTER[\"Cluster · Redis + K8s\u003cbr/\u003emulti-pod, distributed\"]\n        LOCAL -.-\u003e APP\n        SERVER -.-\u003e APP\n        CLUSTER -.-\u003e APP\n    end\n```\n\n## Packages\n\n| Package | Layer | Description |\n|---------|-------|-------------|\n| `@mohanscodex/spectra-ai` | **Provider** | LLM abstraction — stream, complete, register providers. Anthropic, OpenAI, Groq clients with SSE streaming. Core types (Message, Model, ToolCall, StopReason). |\n| `@mohanscodex/spectra-agent` | **Agent** | Agent loop with multi-turn tool dispatch. `defineTool()` with Zod validation, before/after hooks, parallel/sequential execution, retry with backoff, abort support. |\n| `@mohanscodex/spectra-app` | **Infrastructure** *(optional)* | Production utilities you'd build anyway — `SessionEngine` (full lifecycle orchestration), `SessionManager` (CRUD + fork + audit/tree), `SessionStore` (in-memory, filesystem, SQLite, Redis), `LocalRateLimiter` + `RedisRateLimiter` (distributed sliding window), `CompositeRateLimiter` (tenant+user+provider), `CircuitBreaker`, `SseBridge` (SSE with WS-compatible interface), `HealthProbe` (K8s ready). Completely optional — the agent works fine without it. |\n| `spectra-rs` | **Rust Core** | Rust SDK — core types, agent, tools, events. |\n| `spectra-http` | **Rust HTTP** | Rust HTTP clients for Anthropic, OpenAI, Groq, OpenRouter. |\n\n## Feature Matrix\n\n| Feature | TypeScript | Rust |\n|---------|------------|------|\n| Streaming SSE | ✅ | ✅ |\n| Tool Dispatch (Parallel/Sequential) | ✅ | ✅ |\n| Before/After Tool Hooks | ✅ | ✅ |\n| Extension / Middleware System | ✅ | ✅ |\n| Agent Loop (Multi-Turn) | ✅ | ✅ |\n| Retry with Exponential Backoff | ✅ | ✅ |\n| Session Management | ✅ | — |\n| Session Persistence (FS + SQLite) | ✅ | — |\n| Redis Session Store (distributed) | ✅ | — |\n| Worker Pool | ✅ | ✅ |\n| Rate Limiting (in-memory) | ✅ | ✅ |\n| Redis Rate Limiting (distributed) | ✅ | — |\n| Composite Rate Limiting (tenant+user+provider) | ✅ | — |\n| Circuit Breaker | ✅ | ✅ |\n| SSE Bridge (WS-compatible interface) | ✅ | — |\n| Health Probe (K8s ready) | ✅ | ✅ |\n| Agent Registry | ✅ | ✅ |\n| Cost Tracking | ✅ | ✅ |\n| Tool Choice / Reasoning Effort | ✅ | ✅ |\n| Model Registry | ✅ | ✅ |\n| Audit Trail / Provenance | ✅ | — |\n\n## Quick Start\n\n### TypeScript\n\n```bash\nbun add @mohanscodex/spectra-ai @mohanscodex/spectra-agent\n```\n\n```typescript\nimport { Agent, defineTool } from \"@mohanscodex/spectra-agent\";\nimport { z } from \"zod\";\n\nconst searchTool = defineTool({\n  name: \"search\",\n  description: \"Search the web\",\n  parameters: z.object({ query: z.string() }),\n  execute: async ({ query }) =\u003e ({\n    content: [{ type: \"text\", text: `Results for: ${query}` }],\n  }),\n});\n\nconst agent = new Agent({\n  model: { id: \"claude-sonnet-4-5\", provider: \"anthropic\", api: \"messages\" },\n  systemPrompt: \"You are a helpful assistant.\",\n  tools: [searchTool],\n});\n\nfor await (const event of agent.run(\"What is Rust?\")) {\n  if (event.type === \"message_update\") {\n    console.log(event.message.content);\n  }\n}\n```\n\n### TypeScript — Production\n\n```bash\nbun add @mohanscodex/spectra-ai @mohanscodex/spectra-agent @mohanscodex/spectra-app ioredis\n```\n\n```typescript\nimport { SessionEngine, SessionManager, InMemorySessionStore, CompositeRateLimiter, LocalRateLimiter } from \"@mohanscodex/spectra-app\";\n\nconst engine = new SessionEngine({\n  sessionManager: new SessionManager(new InMemorySessionStore()),\n  rateLimiter: new CompositeRateLimiter([\n    { limiter: new LocalRateLimiter(60, 60000), key: \"tenant\" },\n    { limiter: new LocalRateLimiter(10, 60000), key: \"user\" },\n  ]),\n  maxConcurrentSessions: 100,\n});\n\nengine.start();\nconst result = await engine.run(\"user-123\", \"What is Rust?\", undefined, {\n  model: { id: \"claude-sonnet-4-5\", provider: \"anthropic\", api: \"messages\" },\n});\nconsole.log(result.finalMessage); // \"Rust is a systems programming language...\"\n```\n\n### Rust\n\n```toml\n[dependencies]\nspectra-rs = \"0.2\"\nspectra-http = \"0.2\"\ntokio = { version = \"1\", features = [\"full\"] }\n```\n\n```rust\nuse spectra_rs::{AgentBuilder, Model, Provider};\nuse spectra_http::OpenAIClient;\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let client = OpenAIClient::from_env()?;\n\n    let agent = AgentBuilder::new(Model::new(Provider::OpenAI, \"gpt-4o\"))\n        .system_prompt(\"You are a helpful assistant.\")\n        .build(client.into());\n\n    let (mut rx, _channel, _handle) = agent.run(\"Hello!\").await?;\n\n    while let Some(event) = rx.recv().await {\n        println!(\"{:?}\", event?);\n    }\n\n    Ok(())\n}\n```\n\n## Supported Providers\n\n| Provider | TypeScript | Rust | Streaming | Tool Use |\n|----------|------------|------|-----------|----------|\n| **Anthropic** | ✅ | ✅ | SSE | ✅ |\n| **OpenAI** | ✅ | ✅ | SSE | ✅ |\n| **Groq** | — | ✅ | SSE | — |\n\n## Deployment Architecture\n\nThe three TypeScript packages compose for any scale — from local CLI to distributed cloud:\n\n```\n                    ┌─────────────────────────────────────┐\n                    │        @mohanscodex/spectra-app   │\n                    │  SessionEngine ── orchestrates full  │\n                    │  request lifecycle                   │\n                    │                                      │\n                    │  ┌──────────────────────────────┐    │\n                    │  │ SessionManager + SessionStore│    │\n                    │  │ (InMemory | FS | SQLite |    │    │\n                    │  │  Redis + Postgres cold)      │    │\n                    │  ├──────────────────────────────┤    │\n                    │  │ RateLimiter                  │    │\n                    │  │ (Local | Redis | Composite)  │    │\n                    │  ├──────────────────────────────┤    │\n                    │  │ SseBridge → remote clients   │    │\n                    │  ├──────────────────────────────┤    │\n                    │  │ HealthProbe → K8s probes     │    │\n                    │  └──────────────────────────────┘    │\n                    └──────┬──────────────┬────────────────┘\n                           │              │\n              ┌────────────┴──┐   ┌───────┴──────────┐\n              │ spectra-agent │   │   spectra-ai      │\n              │ Agent.run()   │   │   stream(model)   │\n              │ defineTool()  │   │   registerProvider│\n              │ hooks + retry │   │   EventStream     │\n              └───────────────┘   └──────────────────┘\n```\n\n**Local (coding agent):** SQLite store, no rate limiter, works offline\n**Single-server (SaaS MVP):** Redis store + local rate limiter, 1 process\n**Multi-pod (production):** Redis store (shared state), Redis rate limiter (distributed), SseBridge for SSE streaming, CompositeRateLimiter for tenant isolation\n\n## Project Structure\n\n```\nspectra/\n├── packages/\n│   ├── ai/              # @mohanscodex/spectra-ai — LLM providers\n│   ├── agent/           # @mohanscodex/spectra-agent — Agent + tools\n│   ├── app/             # @mohanscodex/spectra-app — SessionEngine + rate limiting + SSE bridge\n├── apps/\n│   └── examples/        # Example usage\n├── crates/\n│   ├── spectra-rs/      # Rust SDK core\n│   └── spectra-http/    # Rust HTTP clients\n└── .github/workflows/   # CI/CD\n```\n\n## Technology Stack\n\n| Component | Technologies |\n|-----------|-------------|\n| **TypeScript SDK** | TypeScript 5.x · Bun · Vitest · Zod |\n| **Rust SDK** | Rust 1.75+ · Tokio · Reqwest (rustls) · serde · thiserror · miette |\n| **Tooling** | Turborepo · cargo |\n\n## Rust Constraints\n\n- **Zero `unsafe`** — No unsafe in core logic\n- **No OpenSSL** — rustls only, no C dependencies\n- **Release profile** — `opt-level = 3`, `lto = \"thin\"`, `codegen-units = 1`, `panic = \"abort\"`\n- **Edition 2024** — Requires Rust 1.86+\n\n## Development\n\n```bash\n# Install\ngit clone https://github.com/codex-mohan/spectra.git\ncd spectra\nbun install\n\n# Build all packages\nbun run build\n\n# Run tests\nbun run test          # TypeScript\ncargo test --workspace  # Rust\n```\n\n## Credits\n\nSpectra was deeply inspired by **[pi-mono](https://github.com/badlogic/pi-mono)** by **Mario Zechner** — a beautifully minimal AI stack that proved an agent framework doesn't need layers of abstraction to be powerful.\n\n## License\n\nMIT © Mohana Krishna","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodex-mohan%2Fspectra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodex-mohan%2Fspectra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodex-mohan%2Fspectra/lists"}