Portable AI agent harness with plugin architecture for managing multiple AI providers, tracking telemetry, and ensuring quality compliance.
About DCYFR
@dcyfr/ai is maintained by DCYFR Labs as part of the DCYFR AI tooling portfolio.
Table of Contents
Features
- 🔌 Plugin Architecture - Extensible validation system with custom agents
- 🔄 Multi-Provider Support - OpenAI, Anthropic, Ollama, Msty Vibe CLI Proxy, GitHub Copilot
- 🎯 Msty Vibe Integration - Unified multi-model routing with local OpenAI-compatible endpoint
- ⚙️ Configuration System - YAML/JSON config with three-layer merge
- 📊 Comprehensive Telemetry - Track usage, costs, quality metrics, performance
- ✅ Validation Harness - Quality gates with parallel/serial execution
Installation
npm install @dcyfr/ai
CLI command name: the package is @dcyfr/ai, but its command-line tool is invoked as dcyfr-ai — not @dcyfr/ai. After installing, run npx dcyfr-ai <command> (or, without installing first, npx -p @dcyfr/ai dcyfr-ai <command>). Running npx @dcyfr/ai … fails with "could not determine executable to run" because the package ships several binaries.
Quick Start
1. Initialize Configuration
npx dcyfr-ai config:init
This creates a .dcyfr.yaml configuration file:
version: "1.0.0"
projectName: my-app
agents:
designTokens:
enabled: true
compliance: 0.90
barrelExports:
enabled: true
pageLayout:
enabled: true
targetUsage: 0.90
testData:
enabled: true
2. Load and Use Configuration
import { loadConfig, ValidationFramework } from "@dcyfr/ai";
// Load configuration (auto-detects .dcyfr.yaml, .dcyfr.json, package.json)
const config = await loadConfig();
// Create validation framework
const framework = new ValidationFramework({
gates: config.validation.gates,
parallel: config.validation.parallel,
});
// Run validation
const report = await framework.validate({
projectRoot: config.project.root,
files: config.project.include,
config: config.agents,
});
console.log(`Validation: ${report.valid ? "PASS" : "FAIL"}`);
Each gate runs the plugins named in its plugins list, which you load with framework.loadPlugins([...]) (see docs/PLUGINS.md). A gate whose plugins aren't loaded runs nothing and is reported with skipped: true. If that gate is required, it fails with a gate-skipped violation naming the missing plugins. A report where no gate ran anything is never valid. Until you load plugins for the default gates, this script prints FAIL.
3. Validate Configuration
# Validate current project config
npx dcyfr-ai config:validate
# Show full configuration
npx dcyfr-ai config:validate --verbose
🔄 Migration Guides
Migrating from LangChain
Why migrate: Smaller bundle footprint than LangChain (see bundlephobia), built-in telemetry, simpler API
// LangChain (before)
import { ChatOpenAI } from "langchain/chat_models/openai";
import { HumanMessage } from "langchain/schema";
const model = new ChatOpenAI({ temperature: 0.9 });
const response = await model.call([new HumanMessage("Hello")]);
// @dcyfr/ai (after)
import {
AgentRuntime,
ProviderRegistry,
TelemetryEngine,
getMemory,
} from "@dcyfr/ai";
const runtime = new AgentRuntime(
"assistant",
new ProviderRegistry({
primaryProvider: "anthropic",
fallbackChain: ["anthropic", "ollama"],
autoReturn: true,
healthCheckInterval: 60_000,
}),
getMemory(),
new TelemetryEngine(),
);
const result = await runtime.execute({ task: "Hello" });
console.log(result.output);
Key Differences:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
