@mzhub/plexus

AI-Native Fullstack Framework for React. Build agent-powered applications with file-based routing and security-first architecture.

Quick Start

npx plexus init    # Create project with src/public structure
npm install        # Install dependencies (package.json pre-configured)
cp .env.example .env
npm run dev        # Start dev servers

Project Structure

my-app/
  src/
    hub/                      # Framework-managed (auto-discovered)
      route/
        home/page.jsx         # / (homepage)
        dashboard/page.jsx    # /dashboard
        users/[id]/page.jsx   # /users/:id (dynamic)
      agent/
        global.js             # All routes
        dashboard/_agent.js   # /dashboard + children
      tools/
        global.js             # All agents
        dashboard.js          # Dashboard agent only
      api/
        users.js              # /_api/users
    main.jsx                  # Entry point
    styles.css                # Global styles
  public/                     # Static assets
  index.html
  vite.config.js              # Uses plexusViteConfig()

Entry Point

// src/main.jsx - generated by init
import { createApp } from "@mzhub/plexus";
import "./styles.css";

createApp(); // Auto-loads routes, mounts to #root

With custom layout:

import { createApp } from "@mzhub/plexus";
import Layout from "@/components/Layout";

createApp({ Layout });

Vite Config

// vite.config.js - generated by init
import { plexusViteConfig } from "@mzhub/plexus/bundler";

export default plexusViteConfig();

With overrides:

export default plexusViteConfig({
  port: 3000,
  serverPort: 3001,
  alias: { "@components": "./src/components" },
});

Routing

File-Based Routes

| File | Route | | ------------------------------- | ------------ | | hub/route/home/page.jsx | / | | hub/route/about/page.jsx | /about | | hub/route/users/[id]/page.jsx | /users/:id |

Dynamic Routes

// src/hub/route/users/[id]/page.jsx
import { useParams } from "react-router-dom";

export default function UserPage() {
  const { id } = useParams();
  return <h1>User: {id}</h1>;
}

Agent Inheritance

hub/agent/
  global.js               # All routes
  dashboard/_agent.js     # /dashboard + children

Tool Scoping

hub/tools/
  global.js       # All agents
  dashboard.js    # Only dashboard agent

API Reference

Client (@mzhub/plexus)

| Export | Description | | -------------------- | ----------------------- | | createApp() | One-liner app setup | | Router | Manual router component | | createAgentProxy() | RPC client for agent | | useAgentRPC() | Streaming chat hook | | compressDOM() | DOM compression |

Bundler (@mzhub/plexus/bundler)

| Export | Description | | ---------------------- | -------------------------- | | plexusViteConfig() | Pre-configured Vite config | | plexusRouterPlugin() | Auto-routing Vite plugin |

AI (@mzhub/plexus/ai)

| Export | Description | | ------------------------ | --------------------------- | | defineAgent() | Create agent with defaults | | agentLoop() | Execute agent with tools | | defineTool() | Create tool with Zod schema | | createOpenAIProvider() | OpenAI/Groq/Cerebras | | createGroqProvider() | Groq (fast inference) | | createGeminiProvider() | Google Gemini |

Runtime (@mzhub/plexus/runtime)

| Export | Description | | ---------------------- | --------------------------- | | createPlexusServer() | WebSocket server factory | | registerAgent() | Explicit agent registration | | discoverRoutes() | File discovery | | startServer() | Start production server | | GlobalAIDefaults | Type for config cascade |

Defining Tools

import { defineTool } from "@mzhub/plexus/ai";
import { z } from "zod";

export const searchProducts = defineTool({
  name: "search_products",
  description: "Search for products",
  schema: z.object({ query: z.string() }),
  execute: async ({ query }) => {
    const results = await db.products.search(query);
    return { success: true, data: results };
  },
});

React Usage

import { createAgentProxy, useAgentRPC } from "@mzhub/plexus";

const agent = createAgentProxy({ agentId: "global" });

function Chat() {
  const { messages, sendMessage, status } = useAgentRPC(agent);

  return (
    <div>
      {messages.map((m, i) => (
        <div key={i}>{m.content}</div>
      ))}
      <button onClick={() => sendMessage("Hello")}>
        {status === "thinking" ? "..." : "Send"}
      </button>
    </div>
  );
}

Config Cascade

Agents inherit defaults from server config:

const server = await createPlexusServer({
  hubDir: "./src/hub",
  ai: {
    maxIterations: 15,
    maxCost: 0.30,
    costPerToken: 0.00002,
  }
});

// Agents inherit these defaults, can override selectively
// hub/agent/support.js
export default {
  provider: createGroqProvider({ ... }),
  maxCost: 0.10,  // Override just this
};

Environment Variables

GROQ_API_KEY=gsk_...
AI_MODEL=llama-3.3-70b-versatile
PORT=3000

CLI Commands

| Command | Description | | -------------- | ----------------------------------------- | | plexus init | Create new project (src/public structure) | | plexus dev | Run dev servers (Vite + WebSocket) | | plexus build | Build for production | | plexus start | Run production server |

Error Handling

The framework provides typed error classes for common failure scenarios:

import { 
  AgentBudgetError,    // Token/cost limit exceeded
  AgentIterationError, // Max iterations reached
  ToolPermissionError  // RBAC check failed
} from "@mzhub/plexus/ai";

Error Types

| Error | Cause | Resolution | | --------------------- | ------------------------------ | ----------------------------------- | | AgentBudgetError | Cost exceeded maxCost | Increase limit or optimize prompts | | AgentIterationError | Loops exceeded maxIterations | Check for tool loops, increase limit| | ToolPermissionError | User lacks requiredRole | Verify user role in session |

Handling in Components

function Chat() {
  const { error, status } = useAgentRPC(agent);
  
  if (error?.name === 'AgentBudgetError') {
    return <div>Session limit reached. Please try again later.</div>;
  }
  
  // ... rest of component
}

Tool Error Responses

Tools should return structured error responses:

execute: async ({ id }) => {
  const item = await db.find(id);
  if (!item) {
    return { success: false, error: "Item not found" };
  }
  return { success: true, data: item };
}

Troubleshooting

Common Issues

WebSocket connection fails

# Check server is running on correct port
curl http://localhost:3001/_plexus/health

# Verify proxy config in vite.config.js
serverPort: 3001  # Must match server port

Routes not loading

# Verify hub directory structure
ls -la src/hub/route/

# Check for page.jsx files (not index.jsx)
find src/hub/route -name "page.jsx"

Agent not responding

# Check API key is set
echo $GROQ_API_KEY

# Verify agent file exports default object
cat src/hub/agent/global.js

Tools not available to agent

# Tools must be in hub/tools/ directory
# Global tools: hub/tools/global.js
# Scoped tools: hub/tools/{agent-name}.js

Debug Mode

Enable verbose logging:

// vite.config.js
export default plexusViteConfig({
  // ... other config
});

// Start with debug
DEBUG=plexus:* npm run dev

Testing Agents Locally

# Run the test-agent script
npm run test:agent

# Or test a specific agent
npx tsx scripts/test-agent.ts --agent=dashboard

License

MIT