weaveIntel Documentation

Protocol-first, capability-driven AI runtime for TypeScript. 42 packages. 20 runnable examples. 13 deployment targets. Zero vendor lock-in.

Overview

weaveIntel is a modular monorepo that provides composable building blocks for building production-grade AI applications - from simple chat completions to multi-agent orchestration with tool calling, RAG, memory, observability, and inter-agent communication.

Why weaveIntel?

Protocol-first - Core defines contracts (interfaces), not implementations. Swap providers without changing application code.

Capability-driven - Models, agents, and tools declare capabilities. The router selects the right model for the job.

Zero vendor lock-in - Core has zero vendor dependencies. Provider packages are thin adapters.

Composable middleware - Intercept any model call with typed middleware for logging, retries, redaction, caching, or custom logic.

Production patterns built in - Fallback chains, budget enforcement, PII redaction, structured output, evaluation suites, and observability from day one.

Quick Start

Prerequisites

Node.js >= 20, npm >= 10

Install

git clone https://github.com/gibyvarghese/weaveintel.git
cd weaveintel
npm install
npm run build

Environment Variables

export OPENAI_API_KEY="sk-..."          # For OpenAI provider
export ANTHROPIC_API_KEY="sk-ant-..."   # For Anthropic provider

Run your first example

# No API key needed - uses fake models
npx tsx examples/02-tool-calling-agent.ts

# With OpenAI
OPENAI_API_KEY=sk-... npx tsx examples/01-simple-chat.ts

# With Anthropic
ANTHROPIC_API_KEY=sk-ant-... npx tsx examples/11-anthropic-provider.ts

Architecture

weaveIntel is structured in six layers. Each layer depends only on the layers below it. Core has zero vendor dependencies.

Core Design Principles

Interfaces in core, implementations in leaf packages - core never imports from providers or runtime packages.

Middleware is generic - Middleware<T, R> works for any request/response pair. Compose with weaveComposeMiddleware().

Everything is capability-gated - HasCapabilities interface + weaveCapabilitySet() let the router and consumers check model abilities at runtime.

Context flows everywhere - ExecutionContext carries userId, traceId, budget, deadline, and cancellation signal through every call.

Core & Models

Agent Orchestration

Knowledge & Retrieval

Tools & Connectivity

Safety & Governance

Observability & Evaluation

Application Layer

Examples (20)

All examples live in the examples/ directory and can be run directly with npx tsx. Most require no API key (they use fake models and in-memory stores).

geneWeave - Example Chatbot App

geneWeave is a full-stack chatbot application included in the weaveIntel repository at apps/geneweave. It demonstrates how to use weaveIntel's packages together in a production-style application with a chat UI, admin dashboard, tool integration, authentication, and SQLite backend.

geneWeave visually displays guardrail results, cognitive evaluation outputs, confidence ratings, and decision-making transparency directly in the chat interface - so users can see not just what the AI decided, but how it reasoned, what guardrails were applied, and how confident it is in the response.

# Run the geneWeave demo
npx tsx examples/12-geneweave.ts

# Or with full environment
cp .env.example .env   # Add your API keys
npm run dev            # Starts at http://localhost:3500

Deployment (13 Platforms)

geneWeave can be deployed to any platform that runs Node.js 20+ or Docker containers. All deployment configs live in the repo.

CI/CD workflows are included for Docker image builds (GHCR), plus manual/automatic deploy workflows for Azure, Fly.io, Google Cloud Run, and AWS.

Environment Variables

Versioning - Fabric Releases

weaveIntel uses Fabric Versioning: each major release is named after a fabric, assigned alphabetically A to Z. Current release: v1.0.0 - Aertex.

Minor releases (e.g., 1.1.0) add features under the same fabric. Patch releases (e.g., 1.1.1) fix bugs. See VERSIONING.md for details.

Tech Stack

TypeScript 5.7+ - strict mode, ESM-first. npm workspaces - monorepo dependency management. Turborepo - parallel builds with dependency-aware caching. Vitest - test runner. Prettier - code formatting.

Contact

For questions, support, or partnership enquiries: hello@servonomics.co.nz

Found a bug? Open an issue on GitHub. Security concerns? Email hello@servonomics.co.nz.