Skip to content

Commit 2de32cd

Browse files
codex-mohancodex-mohan
committed
docs: align vitepress config with project state and update index
1 parent e1e4fd2 commit 2de32cd

69 files changed

Lines changed: 6937 additions & 19 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AGENTS.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -412,3 +412,76 @@ Rules:
412412
- If graphify-out/wiki/index.md exists, navigate it instead of reading raw files
413413
- For cross-module "how does X relate to Y" questions, prefer `graphify query "<question>"`, `graphify path "<A>" "<B>"`, or `graphify explain "<concept>"` over grep — these traverse the graph's EXTRACTED + INFERRED edges instead of scanning files
414414
- After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost)
415+
416+
## For Coding Agents (Cursor, Claude Code, Windsurf, Copilot)
417+
418+
### Quick Reference
419+
420+
| What | Where |
421+
|------|-------|
422+
| TypeScript SDK | `packages/ai/` (providers), `packages/agent/` (agent + tools) |
423+
| Rust SDK | `crates/spectra-rs/` (core), `crates/spectra-http/` (clients) |
424+
| Documentation | `docs/` (VitePress) |
425+
| Full docs plan | `docs/PLAN.md` |
426+
| LLM-friendly docs | `docs/public/llms.txt` |
427+
428+
### When a Developer Asks About Spectra
429+
430+
1. **Determine which language** they need (TypeScript vs Rust) — ask if unclear
431+
2. **Point to the correct docs section** — `/typescript/` or `/rust/` in docs
432+
3. **Provide working, copy-paste examples** — include env var setup
433+
4. **Mention required environment variables** — `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
434+
5. **Never mix TS and Rust** — the SDKs are independent, do not suggest combining them
435+
436+
### Common Patterns
437+
438+
**TypeScript:**
439+
```typescript
440+
import { Agent, defineTool } from "@singularity-ai/spectra-agent";
441+
import { z } from "zod";
442+
443+
const agent = new Agent({
444+
model: { id: "claude-sonnet-4-20250514", name: "Claude", provider: "anthropic", api: "anthropic-messages" },
445+
systemPrompt: "You are a helpful assistant.",
446+
tools: [defineTool({ name: "tool", description: "...", parameters: z.object({}), execute: async () => ({ content: [] }) })],
447+
});
448+
449+
for await (const event of agent.run("Hello")) {
450+
if (event.type === "message_update") { /* stream text */ }
451+
}
452+
```
453+
454+
**Rust:**
455+
```rust
456+
use spectra_rs::{AgentBuilder, Model};
457+
use spectra_http::OpenAIClient;
458+
459+
let client = OpenAIClient::from_env()?;
460+
let agent = AgentBuilder::new().model(Model::openai("gpt-4o")).build(client);
461+
let mut stream = agent.prompt("Hello").await?;
462+
while let Some(event) = stream.next().await { /* handle events */ }
463+
```
464+
465+
### Build & Test Commands
466+
467+
```bash
468+
# TypeScript
469+
bun run lint # tsc --noEmit
470+
bun run test # vitest --run
471+
bun run build # tsc build
472+
bun run docs:dev # vitepress dev (docs)
473+
474+
# Rust
475+
cargo test --workspace
476+
cargo build --release
477+
cargo clippy --workspace
478+
```
479+
480+
### Golden Rules
481+
482+
- Each SDK is **independent** — no shared code, no FFI, no bindings
483+
- Rust: `#![forbid(unsafe_code)]`, `thiserror` + `miette`, `rustls` only (no OpenSSL)
484+
- TypeScript: Zod validation, `EventStream` AsyncIterable, provider registry
485+
- Never use `unwrap`/`expect` in library code — use `?` operator
486+
- API keys always from environment variables, never hardcoded
487+
- Python SDK is TODO — do not implement unless explicitly asked

‎docs/.vitepress/config.ts‎

Lines changed: 153 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,168 @@
11
import { defineConfig } from "vitepress";
2+
import llmstxt from "vitepress-plugin-llms";
23

34
export default defineConfig({
45
title: "Spectra",
56
description: "Minimal, ultra-fast, multi-language AI agent framework",
67
base: "/spectra/",
78
lastUpdated: true,
89
cleanUrls: true,
10+
vite: {
11+
plugins: [
12+
llmstxt({
13+
domain: "https://codex-mohan.github.io/spectra",
14+
generateLLMsTxt: true,
15+
generateLLMsFullTxt: true,
16+
generateLLMFriendlyDocsForEachPage: true,
17+
}),
18+
],
19+
},
920
themeConfig: {
1021
logo: { light: "/logo.svg", dark: "/logo.svg" },
1122
nav: [
12-
{ text: "Guide", link: "/guide/getting-started" },
13-
{ text: "API", link: "/api/agent" },
23+
{ text: "Guide", link: "/getting-started/introduction" },
24+
{ text: "TypeScript", link: "/typescript/overview" },
25+
{ text: "Rust", link: "/rust/overview" },
26+
{ text: "Guides", link: "/guides/adding-a-provider" },
27+
{ text: "Recipes", link: "/recipes/weather-agent" },
28+
{ text: "Reference", link: "/reference/typescript/agent" },
29+
{ text: "GitHub", link: "https://github.com/codex-mohan/spectra" },
1430
],
1531
sidebar: {
32+
"/getting-started/": [
33+
{
34+
text: "Getting Started",
35+
items: [
36+
{ text: "Introduction", link: "/getting-started/introduction" },
37+
{ text: "Installation", link: "/getting-started/installation" },
38+
{ text: "Quickstart", link: "/getting-started/quickstart" },
39+
{ text: "Project Structure", link: "/getting-started/project-structure" },
40+
],
41+
},
42+
],
43+
"/typescript/": [
44+
{
45+
text: "TypeScript SDK",
46+
items: [
47+
{ text: "Overview", link: "/typescript/overview" },
48+
{ text: "Agent", link: "/typescript/agent" },
49+
{ text: "Tools", link: "/typescript/tools" },
50+
{ text: "Providers", link: "/typescript/providers" },
51+
{ text: "Events", link: "/typescript/events" },
52+
{ text: "Session Management", link: "/typescript/sessions" },
53+
{ text: "Orchestration", link: "/typescript/orchestration" },
54+
],
55+
},
56+
],
57+
"/rust/": [
58+
{
59+
text: "Rust SDK",
60+
items: [
61+
{ text: "Overview", link: "/rust/overview" },
62+
{ text: "Getting Started", link: "/rust/getting-started" },
63+
{ text: "Agent", link: "/rust/agent" },
64+
{ text: "Tools", link: "/rust/tools" },
65+
{ text: "Providers", link: "/rust/providers" },
66+
{ text: "Events", link: "/rust/events" },
67+
{ text: "Extensions", link: "/rust/extensions" },
68+
],
69+
},
70+
],
71+
"/guides/": [
72+
{
73+
text: "How-To Guides",
74+
items: [
75+
{ text: "Adding a Provider", link: "/guides/adding-a-provider" },
76+
{ text: "Tool Design Patterns", link: "/guides/tool-design-patterns" },
77+
{ text: "Error Handling", link: "/guides/error-handling" },
78+
{ text: "Prompt Engineering", link: "/guides/prompt-engineering" },
79+
{ text: "Multi-Agent Patterns", link: "/guides/multi-agent-patterns" },
80+
{ text: "Streaming UI", link: "/guides/streaming-ui" },
81+
{ text: "Session Management", link: "/guides/session-management" },
82+
{ text: "Deployment", link: "/guides/deployment" },
83+
],
84+
},
85+
],
86+
"/recipes/": [
87+
{
88+
text: "Recipes",
89+
items: [
90+
{ text: "Weather Agent", link: "/recipes/weather-agent" },
91+
{ text: "Web Search Agent", link: "/recipes/web-search-agent" },
92+
{ text: "RAG Agent", link: "/recipes/rag-agent" },
93+
{ text: "Multi-Agent Research", link: "/recipes/multi-agent-research" },
94+
{ text: "Chatbot with Sessions", link: "/recipes/chatbot-with-sessions" },
95+
{ text: "Rate-Limited API", link: "/recipes/rate-limited-api" },
96+
],
97+
},
98+
],
99+
"/concepts/": [
100+
{
101+
text: "Concepts",
102+
items: [
103+
{ text: "Agent Loop", link: "/concepts/agent-loop" },
104+
{ text: "Streaming Architecture", link: "/concepts/streaming-architecture" },
105+
{ text: "TypeScript vs Rust", link: "/concepts/ts-vs-rust" },
106+
{ text: "Tool Dispatch", link: "/concepts/tool-dispatch" },
107+
{ text: "Event System", link: "/concepts/event-system" },
108+
],
109+
},
110+
],
111+
"/reference/": [
112+
{
113+
text: "TypeScript Reference",
114+
items: [
115+
{ text: "Agent", link: "/reference/typescript/agent" },
116+
{ text: "defineTool", link: "/reference/typescript/define-tool" },
117+
{ text: "EventStream", link: "/reference/typescript/event-stream" },
118+
{ text: "Types", link: "/reference/typescript/types" },
119+
{ text: "SessionManager", link: "/reference/typescript/session-manager" },
120+
{ text: "SessionEngine", link: "/reference/typescript/session-engine" },
121+
{ text: "RateLimiter", link: "/reference/typescript/rate-limiter" },
122+
{ text: "WorkerPool", link: "/reference/typescript/worker-pool" },
123+
{ text: "AgentRegistry", link: "/reference/typescript/agent-registry" },
124+
{ text: "CircuitBreaker", link: "/reference/typescript/circuit-breaker" },
125+
],
126+
},
127+
{
128+
text: "Rust Reference",
129+
items: [
130+
{ text: "AgentBuilder", link: "/reference/rust/agent-builder" },
131+
{ text: "LlmClient", link: "/reference/rust/llm-client" },
132+
{ text: "Tool", link: "/reference/rust/tool" },
133+
{ text: "Messages", link: "/reference/rust/messages" },
134+
{ text: "Events", link: "/reference/rust/events" },
135+
{ text: "Extension", link: "/reference/rust/extension" },
136+
{ text: "Error", link: "/reference/rust/error" },
137+
{ text: "ModelRegistry", link: "/reference/rust/model-registry" },
138+
],
139+
},
140+
],
141+
"/troubleshooting/": [
142+
{
143+
text: "Troubleshooting",
144+
items: [
145+
{ text: "Common Issues", link: "/troubleshooting/common-issues" },
146+
{ text: "Debugging", link: "/troubleshooting/debugging" },
147+
{ text: "FAQ", link: "/troubleshooting/faq" },
148+
],
149+
},
150+
],
151+
"/contribute/": [
152+
{
153+
text: "Contributing",
154+
items: [
155+
{ text: "Setup", link: "/contribute/setup" },
156+
{ text: "Adding Providers", link: "/contribute/adding-providers" },
157+
{ text: "Coding Standards", link: "/contribute/coding-standards" },
158+
{ text: "Architecture Decisions", link: "/contribute/architecture-decisions" },
159+
],
160+
},
161+
],
162+
// Legacy paths — keep for backward compat during migration
16163
"/guide/": [
17164
{
18-
text: "Guide",
165+
text: "Guide (Legacy)",
19166
items: [
20167
{ text: "Getting Started", link: "/guide/getting-started" },
21168
{ text: "Agent", link: "/guide/agent" },
@@ -24,12 +171,13 @@ export default defineConfig({
24171
{ text: "Events", link: "/guide/events" },
25172
{ text: "Session Management", link: "/guide/sessions" },
26173
{ text: "Orchestration & Concurrency", link: "/guide/orchestration" },
174+
{ text: "Rust SDK", link: "/guide/rust" },
27175
],
28176
},
29177
],
30178
"/api/": [
31179
{
32-
text: "TypeScript API",
180+
text: "TypeScript API (Legacy)",
33181
items: [
34182
{ text: "Agent", link: "/api/agent" },
35183
{ text: "Tools", link: "/api/tools" },
@@ -39,7 +187,7 @@ export default defineConfig({
39187
],
40188
},
41189
{
42-
text: "Rust API",
190+
text: "Rust API (Legacy)",
43191
items: [
44192
{ text: "Overview", link: "/api/rust" },
45193
],

0 commit comments

Comments
 (0)