@dcyfr/ai

v1.0.4

Published

8 days ago

Portable AI agent framework with plugin architecture

0High
0Medium
0Low

dcyfr

ai agent framework plugin llm claude copilot automation

@dcyfr/ai

Portable AI agent framework with plugin architecture for multi-provider integration, telemetry tracking, and quality validation.

Portable AI agent framework with plugin architecture for managing multiple AI providers, tracking telemetry, and ensuring quality compliance.

Features

🔌 Plugin Architecture - Extensible validation system with custom agents
🔄 Multi-Provider Support - Claude, Copilot, Groq, Ollama, OpenAI, Anthropic
⚙️ Configuration System - YAML/JSON config with three-layer merge
📊 Comprehensive Telemetry - Track usage, costs, quality metrics, performance
✅ Validation Framework - Quality gates with parallel/serial execution
💾 Pluggable Storage - Memory, file-based, or custom adapters
⚡ Type-Safe - Full TypeScript support with Zod validation
📦 Lightweight - ~200KB gzipped bundle size
🛠️ CLI Tools - Config validation and initialization

Installation

npm install @dcyfr/ai

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'}`);

3. Validate Configuration

# Validate current project config
npx @dcyfr/ai config:validate

# Show full configuration
npx @dcyfr/ai config:validate --verbose

Architecture

The DCYFR AI framework follows a layered architecture with clear separation of concerns:

graph TB
    A[Configuration Files] -->|Load & Merge| B[Config Loader]
    B -->|Initialize| C[Plugin Registry]
    C -->|Register| D[Validation Engine]
    C -->|Register| E[Telemetry Engine]
    D -->|Execute| F[Quality Gates]
    E -->|Track| G[Storage Adapters]
    B -->|Configure| H[CLI Interface]
    H -->|Commands| I[User]

    style A fill:#e1f5ff
    style B fill:#fff3cd
    style C fill:#d4edda
    style D fill:#d4edda
    style E fill:#d4edda
    style H fill:#cfe2ff
    style I fill:#f8d7da

Key Components

Config Loader: Three-layer merge system (defaults → project config → env vars)
Plugin Registry: Manages custom and built-in validation agents
Validation Engine: Executes quality gates in parallel or serial mode
Telemetry Engine: Tracks usage, costs, quality metrics with pluggable storage
CLI Interface: User-facing commands for config management and validation

⬆️ Back to top

Configuration

File Formats

Supports multiple configuration formats (auto-detected):

.dcyfr.yaml / .dcyfr.yml - YAML format (recommended)
.dcyfr.json / dcyfr.config.json - JSON format
package.json - Under dcyfr key

Three-Layer Merge

Configuration is merged from three sources:

Framework Defaults → Project Config → Environment Variables
    (built-in)         (.dcyfr.yaml)      (DCYFR_* vars)

Environment Overrides

Override any config value with environment variables:

DCYFR_TELEMETRY_ENABLED=false
DCYFR_PROVIDERS_PRIMARY=groq
DCYFR_AGENTS_DESIGNTOKENS_COMPLIANCE=0.95

Plugin System

Built-in Agents

DCYFR comes with specialized validation agents:

Design Token Validator - Enforces design system compliance
Barrel Export Checker - Ensures import conventions
PageLayout Enforcer - Validates layout usage patterns
Test Data Guardian - Prevents production data in tests

See @dcyfr/agents for specialized DCYFR agents.

Custom Plugins

import { PluginLoader } from '@dcyfr/ai';

const customPlugin = {
  manifest: {
    name: 'my-validator',
    version: '1.0.0',
    description: 'Custom validation logic',
  },
  async onValidate(context) {
    // Your validation logic
    return {
      valid: true,
      violations: [],
      warnings: [],
    };
  },
};

const loader = new PluginLoader();
await loader.loadPlugin(customPlugin);

⬆️ Back to top

CLI Commands

# Initialize configuration
npx @dcyfr/ai config:init
npx @dcyfr/ai config:init --format json
npx @dcyfr/ai config:init --minimal

# Validate configuration
npx @dcyfr/ai config:validate
npx @dcyfr/ai config:validate --verbose
npx @dcyfr/ai config:validate --config custom.yaml

# Show schema
npx @dcyfr/ai config:schema

# Help
npx @dcyfr/ai help

⬆️ Back to top

Examples

See examples/ directory:

basic-usage.ts - Getting started
plugin-system.ts - Plugin development
configuration.ts - Configuration usage

Documentation

Getting Started
Configuration Guide
Plugin Development
API Reference
Release Management - Publishing and versioning
Quick Release Guide - TL;DR for releases

Contributing

See CONTRIBUTING.md for contribution guidelines.

Release Process

We use Changesets for automated versioning and publishing.

For contributors:

# Add a changeset describing your changes
npm run changeset

# Commit the changeset with your PR
git add .changeset/*.md
git commit -m "feat: your feature"

For maintainers:

Changesets automatically creates Release PRs
Merging a Release PR publishes to npm
See Release Management for full details

⬆️ Back to top

🔧 Troubleshooting

Installation Issues

Issue: npm install @dcyfr/ai fails with 404

Cause: Package may not be published yet or npm registry issue
Solution: Verify package exists: npm view @dcyfr/ai, or install from GitHub: npm install git+https://github.com/dcyfr/dcyfr-ai.git
Check: Visit https://www.npmjs.com/package/@dcyfr/ai to confirm publication status

Issue: "Cannot find module '@dcyfr/ai'"

Cause: Package not in node_modules or incorrect import path
Solution: Run npm install, verify import: import { loadConfig } from '@dcyfr/ai'
TypeScript: Ensure moduleResolution: "bundler" or "node16" in tsconfig.json

Configuration Issues

Issue: .dcyfr.yaml not detected

Cause: File in wrong location or invalid YAML syntax
Solution:
1. Place .dcyfr.yaml in project root (same directory as package.json)
2. Validate YAML syntax with npx @dcyfr/ai config:validate
3. Check for tabs (use spaces), missing colons, incorrect indentation
Alternative: Use .dcyfr.json or add dcyfr key to package.json

Issue: "Invalid configuration schema"

Cause: Missing required fields or incorrect types
Solution:
1. Run npx @dcyfr/ai config:schema to see full schema
2. Ensure required fields present: version, projectName
3. Check types match (strings in quotes, booleans without quotes, arrays with brackets)
Example: Valid config minimum:

version: '1.0.0'
projectName: my-app

Issue: Environment variables not overriding config

Cause: Incorrect env var naming or precedence
Solution: Use DCYFR_ prefix with nested path: DCYFR_AGENTS_DESIGNTOKENS_COMPLIANCE=0.95
Format: DCYFR_<SECTION>_<SUBSECTION>_<KEY>=<value> (uppercase, underscores)
Debug: Log final config to see what values are being used

Plugin Issues

Issue: Custom plugin not loading

Cause: Plugin doesn't implement required interface or missing manifest
Solution: Ensure plugin exports:
1. manifest object with name, version, description
2. onValidate method (async function)
3. Proper TypeScript types if using TypeScript
Example: See examples/plugin-system.ts

Issue: Validation fails with "No plugins loaded"

Cause: Plugins not registered with PluginLoader before validation
Solution:

import { PluginLoader } from '@dcyfr/ai';
const loader = new PluginLoader();
await loader.loadPlugin(myPlugin);
await loader.runValidation();

CLI Issues

Issue: npx @dcyfr/ai command not found

Cause: Package not installed or PATH issue
Solution:
- Local: Add to devDependencies: npm install --save-dev @dcyfr/ai
- Global: npm install -g @dcyfr/ai
- npx: Use full package name: npx @dcyfr/ai@latest

Issue: CLI commands hang or timeout

Cause: Large project or slow file system operations
Solution:
1. Use --files flag to target specific files: npx @dcyfr/ai validate --files "src/**/*.ts"
2. Increase timeout in config: timeout: 60000 (60 seconds)
3. Check for infinite loops in custom plugins

⬆️ Back to top

📚 FAQ

Q: Is @dcyfr/ai published to npm?

A: Yes, it's published as a public package on npm. Install with npm install @dcyfr/ai. Check https://www.npmjs.com/package/@dcyfr/ai for latest version and stats.

Q: Can I use @dcyfr/ai with JavaScript (no TypeScript)?

A: Yes, but TypeScript is strongly recommended for better type safety and IDE support. The framework provides full TypeScript support with Zod validation for runtime type checking. If using JavaScript, you'll miss compile-time type checking but runtime validation still works.

Q: How do I create a custom validation plugin?

A: Implement the Plugin interface with manifest and onValidate method:

export const myPlugin = {
  manifest: {
    name: 'my-plugin',
    version: '1.0.0',
    description: 'My custom validation'
  },
  async onValidate(context) {
    // Your validation logic here
    return { passed: true, issues: [] };
  }
};

See docs/plugins.md and examples/plugin-system.ts for complete guide.

Q: What's the difference between @dcyfr/ai and @dcyfr/agents?

A: @dcyfr/ai is the public framework (plugin architecture, config management, telemetry engine, validation framework). @dcyfr/agents is a private package with DCYFR-specific validation agents (design tokens, barrel exports, PageLayout enforcement). Think of @dcyfr/ai as the engine, @dcyfr/agents as pre-built plugins.

Q: Can I use this with other AI providers (non-Claude)?

A: Yes! The framework supports multi-provider integration including Claude, GitHub Copilot, Groq, Ollama, OpenAI, Anthropic. Configure providers in .dcyfr.yaml:

providers:
  - name: openai
    apiKey: ${OPENAI_API_KEY}
  - name: anthropic
    apiKey: ${ANTHROPIC_API_KEY}

Q: How do I track telemetry and costs?

A: Use the TelemetryEngine with storage adapters:

import { TelemetryEngine, FileStorageAdapter } from '@dcyfr/ai';
const telemetry = new TelemetryEngine({
  storage: new FileStorageAdapter('./telemetry')
});

Telemetry tracks: API calls, token usage, costs, latency, quality scores. See docs/configuration.md for full guide.

Q: Is this framework production-ready?

A: Yes! @dcyfr/ai is used in production at dcyfr-labs and other projects. It has comprehensive test coverage, semantic versioning, automated releases via Changesets, and follows best practices for package publishing.

⬆️ Back to top

📊 Performance Benchmarks

Framework Performance

Config Loading: ~10ms (cached), ~50ms (first load with file I/O)
Validation Framework: Parallel execution 2-5x faster than serial (depends on plugin count)
Plugin System: Minimal overhead ~5ms per plugin registration
Bundle Size: ~200KB gzipped (includes Zod validation library)

Recommended Usage Patterns

Use parallel validation for independent checks (faster): mode: 'parallel'
Cache config loading (use singleton pattern): Load once, reuse across app
Batch telemetry writes (reduce I/O overhead): Buffer writes, flush periodically
Lazy load plugins (faster startup): Only load plugins you need for current validation

Comparison with Alternatives

vs. Custom Scripts: 10-20x faster due to optimized plugin execution
vs. Serial Validation: 2-5x faster with parallel execution mode
vs. LangChain: ~10x smaller bundle size (~200KB vs 2MB+)

⬆️ Back to top

🔒 Security

Reporting Vulnerabilities

Found a security issue? Report it privately:

GitHub Security Advisories: dcyfr-ai/security
Expected Response: Within 48 hours

Security Considerations

No API keys stored: Use environment variables for sensitive data (Zod validates but doesn't store)
Zod validation: All inputs validated with schemas before processing
No remote code execution: Plugins run in local environment only (no sandboxing yet - see limitations)
Telemetry privacy: Optional, disable with DCYFR_TELEMETRY_ENABLED=false
Dependencies: Regular Dependabot updates, npm audit on CI

Best Practices

Never commit .env files (use .env.example)
Use environment variables for API keys: ${OPENAI_API_KEY}
Review plugin code before loading (plugins have full access to filesystem)
Keep dependencies updated: npm outdated, npm update
Enable GitHub security scanning in your repository

⬆️ Back to top

⚙️ Known Limitations

Current Constraints

Plugin isolation: Plugins run in same process (no sandboxing yet) - trust plugin code before loading
File-based telemetry only: No database storage adapter yet (planned for v2.0)
Config caching: Requires manual cache invalidation on config changes (no hot-reload yet)
Provider-specific features: Some providers may have limited support (e.g., streaming not supported for all)
TypeScript required for development: JavaScript works at runtime but TypeScript recommended for development

Platform-Specific Issues

Windows: Path separators handled automatically but some plugins may have issues
Node.js version: Requires ≥18.0.0 (uses native fetch, modern APIs)
ESM-only: Package is ESM (ECMAScript Modules) - CommonJS require() not supported

Planned Improvements

[ ] Database storage adapter for telemetry (PostgreSQL, SQLite)
[ ] Plugin sandboxing for security (worker threads or VM isolation)
[ ] Hot-reload config watching (auto-reload on file changes)
[ ] Web UI for telemetry dashboard (view costs, usage, quality over time)
[ ] Enhanced provider feature parity (streaming, function calling, vision)
[ ] CommonJS compatibility mode (for legacy projects)

See GitHub Issues for tracked feature requests and bugs.

⬆️ Back to top

📄 License & Sponsorship

License: MIT for personal/non-commercial use. Commercial use requires a paid tier.

Commercial Use

This package is dual-licensed:

MIT License for personal, educational, and non-commercial use (free)
Commercial License for business and revenue-generating use (paid)

Commercial use includes:

Using @dcyfr/ai in SaaS products or revenue-generating services
Deploying in companies with >5 employees
Providing paid consulting/services using @dcyfr/ai
Distributing as part of commercial products

Sponsorship Tiers

🌍 Community ($5/mo) - Signal community access (DCYFR.NET, Quantum Flux)
💚 Sponsors ($10/mo) - Bio on dcyfr.ai website + private channels
👨‍💻 Developer ($20/mo) - Limited commercial license + pre-release builds + portfolio support
🚀 Founder ($2,400/yr) - Full commercial license + 1hr consultation/mo
💼 Executive ($4,800/yr) - Business license + 2hr consultation/mo + 50 employees
🏢 Enterprise ($9,600/yr) - Enterprise license + 4hr consultation/mo + unlimited scale

Learn more: SPONSORSHIP.md Join: GitHub Sponsors Contact: [email protected]

Trademark

"DCYFR" is a trademark of DCYFR Labs. See TRADEMARK.md for usage guidelines.

Made with ❤️ by DCYFR Labs

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@dcyfr/ai

Table of Contents

Features

Installation

Quick Start

1. Initialize Configuration

2. Load and Use Configuration

3. Validate Configuration

Architecture

Key Components

Configuration

File Formats

Three-Layer Merge

Environment Overrides

Plugin System

Built-in Agents

Custom Plugins

CLI Commands

Examples

Documentation

Contributing

Release Process

🔧 Troubleshooting

Installation Issues

Configuration Issues

Plugin Issues

CLI Issues

📚 FAQ

📊 Performance Benchmarks

Framework Performance

Recommended Usage Patterns

Comparison with Alternatives

🔒 Security

Reporting Vulnerabilities

Security Considerations

Best Practices

⚙️ Known Limitations

Current Constraints

Platform-Specific Issues

Planned Improvements

📄 License & Sponsorship

Commercial Use

Sponsorship Tiers

Trademark