network-ai 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jovan Marinovic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/QUICKSTART.md

@@ -0,0 +1,260 @@
+# Network-AI Quick Start Guide
+
+Get the Multi-Agent Swarm Orchestrator running in **under 5 minutes**.
+
+---
+
+## 1. Install
+
+```bash
+# Clone the repo
+git clone https://github.com/jovanSAPFIONEER/Network-AI.git
+cd Network-AI
+
+# Install dependencies (only TypeScript + ts-node needed)
+npm install
+
+# Verify everything works
+npx ts-node setup.ts --check
+```
+
+**Zero external AI dependencies.** All 12 adapters are self-contained — add framework SDKs only when you need them.
+
+---
+
+## 2. Pick Your Framework
+
+| Adapter | Framework | Dependency | Use Case |
+|---------|-----------|------------|----------|
+| `custom` | Any | none | Plain functions or HTTP endpoints |
+| `langchain` | LangChain | `langchain` | Chains, agents, RAG |
+| `autogen` | AutoGen/AG2 | `autogen-agentchat` | Multi-agent conversations |
+| `crewai` | CrewAI | none | Role-based agent crews |
+| `mcp` | MCP | `@modelcontextprotocol/sdk` | Tool serving & discovery |
+| `openclaw` | OpenClaw | `openclaw-core` | OpenClaw skill ecosystem |
+| `llamaindex` | LlamaIndex | `llamaindex` | RAG, query engines |
+| `semantic-kernel` | Semantic Kernel | `semantic-kernel` | Enterprise planners & plugins |
+| `openai-assistants` | OpenAI Assistants | `openai` | GPT assistants with threads |
+| `haystack` | Haystack | none | Production RAG pipelines |
+| `dspy` | DSPy | none | Programmatic prompt optimisation |
+| `agno` | Agno | none | Multi-agent teams |
+
+---
+
+## 3. Hello World (30 seconds)
+
+```typescript
+import { createSwarmOrchestrator } from './index';
+import { AdapterRegistry, CustomAdapter } from './adapters';
+
+async function main() {
+  // Create orchestrator
+  const orchestrator = createSwarmOrchestrator({
+    agentId: 'my-app',
+    swarmName: 'My First Swarm',
+  });
+
+  // Create a simple agent
+  const adapter = new CustomAdapter();
+  adapter.registerHandler('greeter', async (payload) => {
+    const name = payload.handoff?.instruction || 'World';
+    return { greeting: `Hello, ${name}!` };
+  });
+
+  // Register it
+  const registry = new AdapterRegistry();
+  await registry.addAdapter(adapter);
+
+  // Execute
+  const result = await registry.executeAgent('custom:greeter', {
+    action: 'greet',
+    params: {},
+    handoff: { instruction: 'Developer' },
+  }, {
+    agentId: 'my-app',
+    taskId: 'task-1',
+    timestamp: Date.now(),
+    priority: 5,
+  });
+
+  console.log(result.data); // { greeting: "Hello, Developer!" }
+}
+
+main();
+```
+
+---
+
+## 4. Multi-Framework Setup
+
+Use different AI frameworks **together** in one orchestrator:
+
+```typescript
+import { AdapterRegistry, CustomAdapter, LlamaIndexAdapter, DSPyAdapter } from './adapters';
+
+async function multiFramework() {
+  const registry = new AdapterRegistry();
+
+  // Framework 1: Custom agents for business logic
+  const custom = new CustomAdapter();
+  custom.registerHandler('validator', async (p) => ({
+    valid: true,
+    message: 'Input validated',
+  }));
+
+  // Framework 2: LlamaIndex for RAG
+  const llamaindex = new LlamaIndexAdapter();
+  llamaindex.registerQueryEngine('knowledge-base', myQueryEngine);
+
+  // Framework 3: DSPy for classification
+  const dspy = new DSPyAdapter();
+  dspy.registerPredictor('classifier', async (inputs) => ({
+    answer: inputs.question?.toString().includes('urgent') ? 'high' : 'low',
+  }));
+
+  // Register all
+  await registry.addAdapter(custom);
+  await registry.addAdapter(llamaindex);
+  await registry.addAdapter(dspy);
+
+  // Route tasks to the right framework
+  await registry.executeAgent('custom:validator', ...);
+  await registry.executeAgent('llamaindex:knowledge-base', ...);
+  await registry.executeAgent('dspy:classifier', ...);
+}
+```
+
+---
+
+## 5. Add Quality Validation
+
+Prevent bad data from entering the shared blackboard:
+
+```typescript
+import { createSwarmOrchestrator } from './index';
+
+const orchestrator = createSwarmOrchestrator({
+  agentId: 'my-app',
+  swarmName: 'Quality-Controlled Swarm',
+  qualityThreshold: 0.7,  // Auto-approve above this score
+  aiReviewCallback: async (entry) => {
+    // Optional: plug in your AI model for borderline entries
+    const score = await myAIModel.evaluate(entry.value);
+    return { approved: score > 0.5, score, reason: 'AI reviewed' };
+  },
+});
+```
+
+---
+
+## 6. Security
+
+```typescript
+import {
+  SecureSwarmGateway,
+  SecureTokenManager,
+  RateLimiter,
+} from './security';
+
+const gateway = new SecureSwarmGateway({
+  rateLimiting: true,
+  auditLogging: true,
+  inputSanitization: true,
+});
+```
+
+---
+
+## 7. Build Your Own Adapter
+
+Create a custom adapter for any framework in ~50 lines:
+
+```typescript
+import { BaseAdapter } from './adapters/base-adapter';
+import type { AgentPayload, AgentContext, AgentResult } from './types/agent-adapter';
+
+export class MyFrameworkAdapter extends BaseAdapter {
+  readonly name = 'my-framework';
+  readonly version = '1.0.0';
+
+  private agents = new Map<string, any>();
+
+  registerAgent(id: string, agent: any): void {
+    this.agents.set(id, agent);
+    this.registerLocalAgent({
+      id, name: id,
+      description: `My agent: ${id}`,
+      status: 'available',
+    });
+  }
+
+  async executeAgent(
+    agentId: string,
+    payload: AgentPayload,
+    context: AgentContext
+  ): Promise<AgentResult> {
+    this.ensureReady();
+    const agent = this.agents.get(agentId);
+    if (!agent) return this.errorResult('NOT_FOUND', `Unknown: ${agentId}`, false);
+
+    const start = Date.now();
+    try {
+      const result = await agent.run(payload.handoff?.instruction || '');
+      return this.successResult(result, Date.now() - start);
+    } catch (e: any) {
+      return this.errorResult('ERROR', e.message, true, e);
+    }
+  }
+}
+```
+
+---
+
+## 8. Run Tests
+
+```bash
+npx ts-node test-standalone.ts    # 79 core tests
+npx ts-node test-security.ts      # 33 security tests
+npx ts-node test-adapters.ts      # 100+ adapter tests (all 12 frameworks)
+```
+
+---
+
+## 9. Commands Reference
+
+```bash
+npx ts-node setup.ts --check      # Verify installation
+npx ts-node setup.ts --list       # List all 12 adapters
+npx ts-node setup.ts --example    # Generate example.ts
+```
+
+---
+
+## Architecture
+
+```
+Your App
+  └── SwarmOrchestrator (index.ts)
+       ├── SharedBlackboard        — Shared state across agents
+       ├── AuthGuardian            — Trust & permissions
+       ├── TaskDecomposer          — Break tasks into subtasks
+       ├── BlackboardValidator     — Quality gate (Layer 1)
+       ├── QualityGateAgent        — AI review (Layer 2)
+       └── AdapterRegistry         — Routes to any framework
+            ├── CustomAdapter       ─── your functions / HTTP
+            ├── LangChainAdapter    ─── LangChain / LangGraph
+            ├── AutoGenAdapter      ─── Microsoft AutoGen
+            ├── CrewAIAdapter       ─── CrewAI crews
+            ├── MCPAdapter          ─── Model Context Protocol
+            ├── OpenClawAdapter     ─── OpenClaw skills
+            ├── LlamaIndexAdapter   ─── LlamaIndex engines
+            ├── SemanticKernelAdapter── Semantic Kernel
+            ├── OpenAIAssistantsAdapter── OpenAI Assistants
+            ├── HaystackAdapter     ─── Haystack pipelines
+            ├── DSPyAdapter         ─── DSPy modules
+            └── AgnoAdapter         ─── Agno agents/teams
+```
+
+---
+
+**Questions?** Open an issue at [github.com/jovanSAPFIONEER/Network-AI](https://github.com/jovanSAPFIONEER/Network-AI)