NexusAI CAP: A Multi-Provider Open-Source AI Agent Ecosystem

What it is

NexusAI CAP (github.com/Shivay00001/nexusaicap) — "Comprehensive AI Platform" — is a modular Python framework for building autonomous AI agents. Instead of wiring one LLM provider into your app, NexusAI gives you a single interface over many: one config object, one agent orchestrator, one tool registry — with per-provider adapters behind the scenes, a 7-role agent pipeline for autonomous task execution, a RAG pipeline, a plugin system, an MCP server, and a FastAPI web dashboard.

The pitch in one sentence: describe a task, and NexusAI plans it, researches it, picks tools, writes code, reviews the code, audits it, and verifies it — against whichever LLM backend you configured.

The problem it solves

Every agent project hits the same plumbing problem: you start with one provider's SDK, then you need a second provider for cost or availability, then you need tools, then you need RAG, and suddenly you're maintaining a bespoke framework. NexusAI CAP is an attempt to build that framework once, as a pip-installable package with optional dependency groups so you only install what you use:

pip install "."                    # core only
pip install ".[openai,anthropic]"  # core + two providers
pip install ".[all]"               # RAG, web, all providers, tools

pip install ".[rag]" pulls faiss-cpu, sentence-transformers, chromadb, pypdf, python-docx, beautifulsoup4; .[web] pulls FastAPI, uvicorn, websockets; .[tools] pulls gitpython, pandas, and friends. The base install is just httpx, rich, click, pydantic, pyyaml, python-dotenv, aiohttp, jinja2.

How it works: architecture

nexusaicap/
├── nexusai/
│   ├── cli.py                 # run / chat / server commands
│   ├── core/
│   │   ├── config.py          # NexusConfig: YAML + env, provider auto-detect
│   │   ├── registry.py        # tool registry
│   │   └── exceptions.py
│   ├── providers/             # 15 concrete adapters + base + auto selector
│   ├── agents/
│   │   └── orchestrator.py    # 7-role pipeline
│   ├── tools/                 # base framework + tool implementations
│   ├── rag/pipeline.py        # RAG with faiss/chromadb
│   ├── mcp/server.py          # Model Context Protocol server
│   ├── memory/conversation.py # conversation memory
│   ├── plugins/manager.py     # plugin system (+ builtin)
│   └── web/app.py             # FastAPI dashboard + static/index.html
├── nodejs/                    # thin TypeScript client/stubs
├── pyproject.toml / Dockerfile / docker-compose.yml / .env.example
└── LICENSE (MIT)

Configuration: one object, auto-detecting

nexusai/core/config.py builds NexusConfig from a YAML file (~/.nexusai/config.yaml), environment variables, or programmatic kwargs. The clever bit: it maps 18 providers to their env-var key names (PROVIDER_ENV_KEYS) and auto-detects which API keys are present, selecting the best available provider without you naming one. Defaults live in DEFAULT_MODELS (OpenAI → gpt-4o, Anthropic → claude-sonnet-4-20250514, Gemini → gemini-2.0-flash, Groq → llama-3.3-70b-versatile, Ollama → llama3.2). Local/free backends need no keys at all: Ollama (local), g4f (free), Pollinations (free cloud API), Needle (local on-device via WASM).

Provider abstraction: one interface per backend

providers/base.py defines BaseProvider plus Message and Response types, and each backend gets its own module: openai_provider.py, anthropic_provider.py, gemini_provider.py, groq_provider.py, mistral_provider.py, cohere_provider.py, together_provider.py, huggingface_provider.py, fireworks_provider.py, deepseek_provider.py, openrouter_provider.py, pollinations_provider.py, g4f_provider.py, ollama_provider.py, needle_provider.py, plus auto.py for automatic selection. Honest count: that's 15 concrete adapters, with env mappings for 18 (xAI, Cerebras, and Perplexity are mapped in config but don't have dedicated adapter files yet).

The 7-role agent pipeline

nexusai/agents/orchestrator.py (~17 KB) is the brain. A task flows through seven specialized roles:

Planner → Researcher → Tool Manager → Coder → Reviewer → Auditor → Verifier

A TaskContext dataclass carries the shared state through the pipeline — plan, research, selected tools, generated code, code output, review feedback, audit report, verification — with iteration count, error list, status (pending/running/completed/failed), and timing, plus a to_dict() summary for monitoring. The orchestrator exposes run(task) for autonomous execution and chat(input) for interactive use, both driven by the system prompt that grants the agent tool and code-execution access.

Tools: auto-registering framework

tools/base.py is a small piece of genuinely nice framework design. BaseTool subclasses auto-register via __init_subclass__: every public method carrying the @tool decorator's _tool_meta is registered as <tool_name>.<method_name> in the ToolRegistry, in OpenAI function-calling schema format. ToolResult is a dataclass (success, output, error, metadata) with to_dict() serialization.

Implemented tool families include file_tools (~6.6 KB), shell_tools (~5.2 KB), system_tools (~15 KB — system metrics and operations), python_tools (~4.4 KB — code execution), web_tools (~5.4 KB), search_tools (~3.6 KB), git_tools (~3.2 KB), github_tools (~2.8 KB), data_tools (~4.9 KB), math_tools (~3.3 KB), network_tools (~2.9 KB), and crypto_tools (~2.8 KB). Honest caveat: eight category modules (api_tools, archive_tools, calendar_tools, database_tools, docker_tools, image_tools, pdf_tools, text_tools) are 72-byte stubs — the registry skeleton is there, the implementations aren't. The nodejs/ TypeScript surface is likewise minimal (a few hundred bytes per file).

RAG, MCP, memory, plugins, web

• rag/pipeline.py (~14.4 KB): document ingestion and retrieval over faiss/ChromaDB with sentence-transformers embeddings; parsers for PDF, DOCX, HTML, Markdown.
• mcp/server.py: a Model Context Protocol server so external agents can use NexusAI's tools.
• memory/conversation.py: conversation memory (with ~/.nexusai/memory as the store location).
• plugins/manager.py (+ builtin/): plugin loading for extending the platform.
• web/app.py + web/static/index.html (~10.9 KB): a FastAPI dashboard with WebSocket streaming for live agent monitoring.

The CLI

Three commands:

nexusai --help
nexusai run "Build a REST API with FastAPI" --provider groq --model llama-3.3-70b-versatile
nexusai chat --provider ollama
nexusai server --port 8080

run executes a task autonomously through the 7-role pipeline, chat is an interactive REPL, and server starts the web dashboard. A Dockerfile and docker-compose file ship for containerized deployment (API keys go in .env, per the included .env.example).

How to run it

git clone https://github.com/Shivay00001/nexusaicap.git
cd nexusaicap
pip install ".[all]"          # or a smaller extra, e.g. ".[ollama]"
cp .env.example .env          # add your API keys (optional if using Ollama)
nexusai chat                  # or: nexusai run "your task"

Python 3.9+ is supported. The cheapest way to try it is Ollama (local, no key) or Pollinations (free cloud API) — both are first-class in the provider map.

Provider adapter pattern

Each adapter is a self-contained module implementing the BaseProvider interface (Message/Response types in providers/base.py), which keeps provider quirks isolated — a retry or auth change for one backend touches one file. providers/auto.py implements the automatic selection: given the detected keys in NexusConfig, it picks the best available provider. The .env.example (~1.3 KB) documents every expected key, so onboarding is "copy the file, paste your keys."

The supporting systems

• core/registry.py (~6.7 KB) — the ToolRegistry that BaseTool subclasses register into; the single source of truth for what the agent can call.
• core/exceptions.py — typed errors (AgentError, ToolError, ConfigError) so failures are catchable and diagnosable rather than stringly-typed.
• rag/pipeline.py (~14.4 KB) — document ingestion (PDF, DOCX, HTML, Markdown parsers) → chunking → sentence-transformers embeddings → faiss/ChromaDB vector stores → retrieval. This is a complete RAG loop, not a wrapper stub.
• mcp/server.py (~2.7 KB) — exposes NexusAI's tools over the Model Context Protocol, so external agents (Claude Code, Cursor, anything MCP-speaking) can consume them.
• memory/conversation.py (~3.4 KB) — conversation memory with the store rooted at ~/.nexusai/memory.
• plugins/manager.py (~2.2 KB) + plugins/builtin/ — plugin loading for extending the platform without forking it.
• web/app.py (~3.4 KB) + web/static/index.html (~10.9 KB) — FastAPI dashboard with WebSocket streaming, so you can watch the 7-role pipeline execute live: which role is active, what tools were called, what the code output was.

The nodejs/ directory is a thin TypeScript surface (client.ts, provider/tool/agent index stubs, a few hundred bytes each) — treat it as a placeholder; the platform is Python in practice.

Docker and one-command start

A Dockerfile and docker-compose.yml ship in the repo, and the tagline — "ready to use with just one command" — refers to docker compose up --build (with API keys in .env) or the even simpler pip install ".[ollama]" && nexusai chat path. The packaging story is coherent: the same pyproject.toml that defines the optional extras also defines the nexusai console script, so install and CLI are one step. For a framework that could easily be "clone, then spend an afternoon wiring," that's a meaningful reduction in time-to-first-agent.

Honest status

Status: working developer framework / advanced demo. The architecture is genuinely implemented — config auto-detection, 15 provider adapters, the 7-role orchestrator, the auto-registering tool framework, RAG pipeline, MCP server, plugin manager, and web dashboard all have real code behind them. What to know before adopting it:

1. Provider calls need real keys (or a running Ollama). The abstraction is tested by design, not by a test suite I could find — there are no tests in the repo.
2. Tool coverage is uneven: a dozen tool families are implemented; eight are stubs. Budget time to implement the ones you need or to verify the implemented ones against your use case.
3. README claims ("20+ providers", "2000+ tools") outrun the code — 15 adapters and a dozen implemented tool families is still a lot, but count what exists.
4. The nodejs/ surface is a stub; treat the platform as Python-only for now.

Roadmap-shaped gaps: fill the eight stub tool modules, add a test suite (provider mocks + orchestrator pipeline tests), implement the xAI/Cerebras/Perplexity adapters, harden the dashboard auth story (it's currently a dev dashboard), and add evals for the 7-role pipeline so agent quality is measurable rather than asserted.

Who should look at this

If you're building agents and tired of re-plumbing provider SDKs: the providers/ abstraction and the BaseTool auto-registration pattern are worth studying even if you don't adopt the whole platform. If you want a multi-provider agent playground you can run in one command against a free backend (Ollama, Pollinations, g4f): this is ready to clone.

Frequently asked questions