{"id":44917006,"url":"https://github.com/nevindra/oasis","last_synced_at":"2026-04-10T12:05:45.846Z","repository":{"id":338806730,"uuid":"1159144798","full_name":"nevindra/oasis","owner":"nevindra","description":"The AI agent framework Go deserves — composable, interface-driven, and built for where AI is going.","archived":false,"fork":false,"pushed_at":"2026-04-09T13:08:47.000Z","size":2315,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-09T15:11:27.710Z","etag":null,"topics":["ai","ai-agent","ai-framework","go","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nevindra.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":null,"dco":null,"cla":null}},"created_at":"2026-02-16T11:22:48.000Z","updated_at":"2026-03-31T06:55:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"ceed12cd-e6cc-4cc5-93a5-8195089be3b6","html_url":"https://github.com/nevindra/oasis","commit_stats":null,"previous_names":["nevindra/oasis"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/nevindra/oasis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevindra%2Foasis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevindra%2Foasis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevindra%2Foasis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevindra%2Foasis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nevindra","download_url":"https://codeload.github.com/nevindra/oasis/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevindra%2Foasis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31641493,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai","ai-agent","ai-framework","go","golang"],"created_at":"2026-02-18T02:10:45.910Z","updated_at":"2026-04-10T12:05:45.840Z","avatar_url":"https://github.com/nevindra.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Oasis\n\nA high-performance Go framework for AI agent systems — fast, reliable, and built to scale with the next leap in AI capabilities. Single agents, multi-agent networks, DAG workflows, graph-powered RAG, code execution, and long-term memory.\n\n```go\nimport oasis \"github.com/nevindra/oasis\"\n```\n\n## Why Oasis?\n\nMost agent frameworks are wrappers around LLM SDKs with hardcoded abstractions. Oasis is different:\n\n- **Opinionated core, composable edges.** The execution loop, memory pipeline, and suspend/resume are framework-owned and optimized as a unit. Providers, tools, stores, and processors are open interfaces — swap any implementation.\n- **Agents compose recursively.** An `LLMAgent` is an `Agent`. A `Network` of agents is an `Agent`. A `Workflow` containing both is an `Agent`. Nest them arbitrarily.\n- **No LLM SDKs.** Every provider uses raw `net/http`. You control the bytes. Zero vendor lock-in, minimal dependencies.\n- **Go-native concurrency.** Parallel tool dispatch, background agents via `Spawn()`, DAG workflows with automatic wave execution — all using goroutines and channels.\n- **Production primitives, not demos.** Rate limiting, retry with backoff, batch processing, persistent Graph RAG, semantic memory with decay, suspend/resume, Docker-based sandbox with code execution, shell, file I/O, browser, and MCP.\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n    oasis \"github.com/nevindra/oasis\"\n    \"github.com/nevindra/oasis/provider/gemini\"\n    \"github.com/nevindra/oasis/tools/knowledge\"\n    \"github.com/nevindra/oasis/tools/search\"\n)\n\nfunc main() {\n    // Use any provider — Gemini, OpenAI, Groq, Ollama, DeepSeek, Mistral, vLLM, etc.\n    llm := gemini.New(apiKey, \"gemini-2.5-flash\")\n    // Or: llm := openaicompat.NewProvider(\"sk-xxx\", \"gpt-4o\", \"https://api.openai.com/v1\")\n    // Or: llm := openaicompat.NewProvider(\"\", \"llama3\", \"http://localhost:11434/v1\")\n    embedding := gemini.NewEmbedding(apiKey, \"text-embedding-004\", 768)\n\n    agent := oasis.NewLLMAgent(\"assistant\", \"Helpful research assistant\", llm,\n        oasis.WithTools(\n            knowledge.New(store, embedding),\n            search.New(embedding, braveKey),\n        ),\n        oasis.WithPrompt(\"You are a helpful research assistant.\"),\n        oasis.WithConversationMemory(store, oasis.CrossThreadSearch(embedding)),\n        oasis.WithUserMemory(memoryStore, embedding),\n    )\n\n    result, err := agent.Execute(ctx, oasis.AgentTask{Input: \"What is quantum computing?\"})\n}\n```\n\n## Features\n\n### Agent Primitives\n\n- **LLMAgent** — single LLM with tools. Runs a tool-calling loop until the model produces a final response. Multiple tool calls execute in parallel automatically.\n- **Network** — coordinates multiple agents via an LLM router. Subagents appear as callable tools (`agent_\u003cname\u003e`). Networks nest recursively.\n- **Workflow** — deterministic DAG-based orchestration with `Step`, `AgentStep`, `ToolStep`, `ForEach`, `DoUntil`/`DoWhile`. Steps without dependencies run concurrently. Compile-time validation (cycles, missing deps, duplicates).\n- **Background agents** — `Spawn()` launches agents in goroutines with `AgentHandle` for lifecycle tracking, cancellation, and `select`-based multiplexing.\n\n### Intelligence\n\n- **Code execution** — Docker-based sandbox with 7 auto-registered tools: shell, code execution (Python/JS/Bash), file read/write, browser automation, screenshot capture, and MCP server integration. No external orchestration service needed.\n- **Plan execution** — LLM batches multiple tool calls in a single turn via `execute_plan`. All steps run in parallel without re-sampling. Reduces latency and tokens for fan-out patterns.\n- **Dynamic configuration** — per-request resolution of prompt, model, and tool set via `WithDynamicPrompt`, `WithDynamicModel`, `WithDynamicTools`. Multi-tenant personalization, tier-based model selection, role-based tool gating.\n- **Structured output** — `WithResponseSchema` enforces JSON output at the agent level. `SchemaObject` typed builder for compile-time safety.\n- **Suspend/Resume** — pause agent or workflow execution to await external input, then continue from where it left off.\n\n### Memory \u0026 RAG\n\n- **Conversation memory** — load/persist history per thread with `MaxHistory` and `MaxTokens` trimming.\n- **Cross-thread recall** — semantic search across all threads with cosine similarity filtering.\n- **User memory** — LLM-extracted facts with semantic deduplication, confidence decay, and contradiction supersession. Runs automatically after each turn.\n- **Graph RAG** — LLM-based graph extraction during ingestion discovers 8 relationship types between chunks. `GraphRetriever` combines vector search with multi-hop BFS traversal. Persistent `GraphStore` in all store backends.\n- **Hybrid retrieval** — `HybridRetriever` fuses vector search + FTS keyword search with Reciprocal Rank Fusion, parent-child chunk resolution, and optional LLM re-ranking.\n- **Semantic chunking** — embedding-based topic boundary detection alongside recursive and markdown-aware chunkers.\n- **Skills** — file-based instruction packages. Agents discover, activate, and create skills at runtime via `SkillProvider`.\n\n### Streaming \u0026 Events\n\n- **Structured streaming** — `StreamEvent` with 5 typed events: `TextDelta`, `ToolCallStart`, `ToolCallResult`, `AgentStart`, `AgentFinish`. Full visibility into agent execution.\n- **Execution traces** — every `AgentResult` includes `Steps []StepTrace` with per-tool timing, token usage, and input/output. No OTEL setup required.\n- **SSE helper** — `ServeSSE` streams agent responses as Server-Sent Events with zero boilerplate.\n\n### Resilience\n\n- **Retry** — `WithRetry` wraps any provider with exponential backoff on 429/503.\n- **Rate limiting** — `WithRateLimit` with sliding-window RPM and TPM accounting. Blocks requests until budget allows.\n- **Batch processing** — `BatchProvider` and `BatchEmbeddingProvider` for async offline jobs at reduced cost.\n- **Processor pipeline** — `PreProcessor`, `PostProcessor`, `PostToolProcessor` hooks for guardrails, PII redaction, logging. `ErrHalt` short-circuits execution.\n- **Human-in-the-loop** — `InputHandler` lets agents pause and ask humans for input, both LLM-driven (`ask_user` tool) and programmatic.\n\n### Observability\n\n- **Deep tracing** — `Tracer` and `Span` interfaces in the root package. Span hierarchy: `agent.execute` → `agent.memory.load` / `agent.loop.iteration` → `agent.memory.persist`. Zero overhead when no tracer configured.\n- **Structured logging** — all framework logging uses `slog`. Pass `WithLogger(*slog.Logger)` to any agent.\n- **OTEL integration** — `observer.NewTracer()` backed by the global `TracerProvider`.\n\n## Agents in Depth\n\n### LLMAgent\n\n```go\nresearcher := oasis.NewLLMAgent(\"researcher\", \"Searches the web\", llm,\n    oasis.WithTools(searchTool, knowledgeTool),\n    oasis.WithPrompt(\"You are a research specialist.\"),\n    oasis.WithMaxIter(5),\n    oasis.WithSandbox(sb, sandbox.Tools(sb)...),  // sandbox: shell, code, files, browser, MCP\n    oasis.WithPlanExecution(),           // let the LLM batch tool calls\n    oasis.WithTracer(observer.NewTracer()),\n)\n```\n\n### Network\n\n```go\nresearcher := oasis.NewLLMAgent(\"researcher\", \"Searches for information\", llm,\n    oasis.WithTools(searchTool),\n)\nwriter := oasis.NewLLMAgent(\"writer\", \"Writes polished content\", llm)\n\nteam := oasis.NewNetwork(\"team\", \"Research and writing team\", router,\n    oasis.WithAgents(researcher, writer),\n    oasis.WithTools(knowledgeTool),\n)\n\n// Networks compose recursively — a Network is just another Agent\norg := oasis.NewNetwork(\"org\", \"Full organization\", ceo,\n    oasis.WithAgents(team, opsTeam),\n)\n```\n\n### Workflow\n\n```go\npipeline, err := oasis.NewWorkflow(\"research-pipeline\", \"Research and write\",\n    oasis.Step(\"prepare\", func(ctx context.Context, wCtx *oasis.WorkflowContext) error {\n        wCtx.Set(\"query\", \"Research: \"+wCtx.Input())\n        return nil\n    }),\n    oasis.AgentStep(\"research\", researcher, oasis.InputFrom(\"query\"), oasis.After(\"prepare\")),\n    oasis.AgentStep(\"write\", writer, oasis.InputFrom(\"research.output\"), oasis.After(\"research\")),\n    oasis.WithOnError(func(step string, err error) { log.Printf(\"%s failed: %v\", step, err) }),\n)\n\nresult, err := pipeline.Execute(ctx, oasis.AgentTask{Input: \"Go error handling\"})\n```\n\nStep types: `Step` (function), `AgentStep` (delegate to Agent), `ToolStep` (call a tool), `ForEach` (iterate with concurrency), `DoUntil`/`DoWhile` (loop). Workflows can also be defined from JSON at runtime via `FromDefinition` for visual workflow builders.\n\n### Streaming\n\n```go\nif sa, ok := agent.(oasis.StreamingAgent); ok {\n    ch := make(chan oasis.StreamEvent)\n    go func() {\n        for event := range ch {\n            switch event.Type {\n            case oasis.EventTextDelta:\n                fmt.Print(event.Content)\n            case oasis.EventToolCallStart:\n                fmt.Printf(\"\\n[calling %s]\\n\", event.Name)\n            case oasis.EventToolCallResult:\n                fmt.Printf(\"[%s returned]\\n\", event.Name)\n            }\n        }\n    }()\n    result, err := sa.ExecuteStream(ctx, task, ch)\n}\n```\n\n### Background Agents\n\n```go\nh := oasis.Spawn(ctx, agent, task)\n\nfmt.Println(h.State()) // Running, Completed, Failed, Cancelled\nresult, err := h.Wait()\nh.Cancel()\n```\n\n## Core Interfaces\n\n| Interface | Purpose |\n| --------- | ------- |\n| `Provider` | LLM backend — `Chat`, `ChatStream` |\n| `EmbeddingProvider` | Text-to-vector embedding |\n| `Store` | Persistence with vector search, keyword search, graph storage |\n| `MemoryStore` | Long-term semantic memory (facts, confidence, decay) |\n| `Tool` | Pluggable capability for LLM function calling |\n| `Agent` | Composable work unit — `LLMAgent`, `Network`, `Workflow`, or custom |\n| `StreamingAgent` | Token streaming with structured events |\n| `InputHandler` | Human-in-the-loop — pause and request human input |\n| `Tracer` / `Span` | Tracing abstraction (zero OTEL imports in your code) |\n| `Retriever` | Composable retrieval with re-ranking |\n| `Sandbox` / `Manager` | Docker-based sandbox with shell, code, file I/O, browser, MCP |\n\n## Included Implementations\n\n| Component | Packages |\n| --------- | -------- |\n| **Providers** | `provider/gemini` (Google Gemini), `provider/openaicompat` (OpenAI, Groq, Together, DeepSeek, Mistral, Ollama, vLLM, LM Studio, OpenRouter, Azure, and any OpenAI-compatible API) |\n| **Storage** | `store/sqlite` (local, pure-Go), `store/postgres` (PostgreSQL + pgvector). Both support `Store`, `MemoryStore`, `GraphStore`, and `KeywordSearcher` |\n| **Tools** | `tools/knowledge` (RAG), `tools/remember`, `tools/search` (web), `tools/schedule`, `tools/shell`, `tools/file`, `tools/http`, `tools/data` (CSV/JSON transform), `tools/skill` (agent skill management) |\n| **Sandbox** | `sandbox` (Docker-based sandbox), `sandbox/ix` (manager + ix daemon client) |\n| **Retrieval** | `HybridRetriever` (vector + FTS + RRF), `GraphRetriever` (multi-hop BFS), `ScoreReranker`, `LLMReranker` |\n| **Ingestion** | `ingest` (HTML, Markdown, CSV, JSON, DOCX, PDF extractors; recursive, markdown, semantic chunkers; parent-child strategy) |\n| **Observability** | `observer` (OpenTelemetry-backed `Tracer` implementation) |\n\n## Installation\n\n```bash\ngo get github.com/nevindra/oasis\n```\n\nRequires Go 1.24+.\n\n## Project Structure\n\n```text\noasis/\n|-- types.go, provider.go, tool.go     # Core interfaces and domain types\n|-- store.go, memory.go\n|-- agent.go, llmagent.go, network.go   # Agent primitives\n|-- workflow.go                         # DAG orchestration\n|-- processor.go                        # Processor pipeline\n|-- input.go                            # Human-in-the-loop\n|-- retriever.go                        # Retrieval pipeline\n|-- handle.go                           # Spawn() + AgentHandle\n|\n|-- provider/gemini/                    # Google Gemini provider\n|-- provider/openaicompat/              # OpenAI-compatible provider\n|-- store/sqlite/                       # Local SQLite (pure-Go, no CGO)\n|-- store/postgres/                     # PostgreSQL + pgvector\n|-- sandbox/                           # Docker-based sandbox (shell, code, files, browser, MCP)\n|-- observer/                           # OTEL observability\n|-- ingest/                             # Document chunking pipeline\n|-- tools/                              # Built-in tools\n|\n|-- cmd/bot_example/                    # Reference application\n```\n\n## Configuration\n\nConfig loading order: **defaults -\u003e `oasis.toml` -\u003e environment variables** (env vars win).\n\nSee [docs/configuration/reference.md](docs/configuration/reference.md) for the full reference.\n\n## Documentation\n\n- [Getting Started](docs/getting-started/) — installation, quick start, reference app\n- [Concepts](docs/concepts/) — architecture, interfaces, and primitives\n- [Guides](docs/guides/) — how-to guides for building custom components\n- [API Reference](docs/api/) — complete interface definitions, types, and options\n- [Configuration](docs/configuration/reference.md) — all config options and environment variables\n- [Philosophy](docs/PHILOSOPHY.md) — design principles and framework identity\n- [Engineering](docs/ENGINEERING.md) — coding standards and production rules\n- [Deployment](cmd/bot_example/DEPLOYMENT.md) — Docker, cloud deployment for the reference bot\n\n## MCP Docs Server\n\nOasis ships an MCP (Model Context Protocol) server that exposes framework documentation to AI assistants. Connect it to Claude Code, Cursor, Windsurf, or any MCP-compatible tool.\n\n```json\n{\n  \"mcpServers\": {\n    \"oasis\": {\n      \"type\": \"stdio\",\n      \"command\": \"go\",\n      \"args\": [\"run\", \"github.com/nevindra/oasis/cmd/mcp-docs@latest\"]\n    }\n  }\n}\n```\n\nAll docs are embedded at build time via `//go:embed`. No network access, no API keys — runs as a local subprocess.\n\n## License\n\n[AGPL-3.0](LICENSE) — commercial licensing available, contact nevindra for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnevindra%2Foasis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnevindra%2Foasis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnevindra%2Foasis/lists"}