zayra-config

The centralized configuration management package of ZAYRA AI. Version 0.0.2 upgrades zayra-config into a complete configuration layer for multi-model, multi-provider ZAYRA AI: providers, model selection, plugins, user preferences, and security settings — while continuing to only manage configuration (no AI execution, no API calls, no model-selection logic, no tool execution).

Installation

npm install zayra-config

Upgrading from 0.0.1

Do not hand-edit files. Run the migration script instead:

node scripts/update-v0.0.2.js

It backs up package.json, src/, and any configuration files into backup/<timestamp>/, writes the updated src/ files, bumps package.json to 0.0.2, migrates an existing config.json (if present) from the old flat shape into the new nested shape, and verifies the migration by actually loading and validating the new config end-to-end. If anything goes wrong, it automatically restores your previous state. See "Migration script" below for details.

Usage

import { ConfigManager, createDefaultValidator } from "zayra-config";

const config = new ConfigManager({ validator: createDefaultValidator() });
await config.load();

config.get("ai.provider");          // "auto" by default
config.get("providers.groq.enabled"); // false by default
config.validate();                    // throws ValidationError if anything's off

Configuration shape (v0.0.2)

{
  ai: { provider: "auto", model: "auto", fallback: true },
  memory: { enabled: true },
  system: { debug: false },
  providers: {
    groq: { enabled: false },
    gemini: { enabled: false },
    openai: { enabled: false },
    openrouter: { enabled: false },
    local: { enabled: false },
  },
  models: { autoSelect: true, selectionMode: "smart" },
  plugins: { enabled: true, installed: [] },
  user: {
    theme: "dark",
    language: "en",
    personality: "default",
    responseStyle: "balanced",
    privacy: "standard",
  },
  security: {
    permissions: { allowFileAccess: false, allowNetworkAccess: false, allowShellExecution: false },
    secretManagement: { source: "env", allowInlineSecrets: false },
    accessControl: { requireAuth: false, allowedUsers: [] },
  },
}

Sources and priority, same as v0.0.1: process.env (ZAYRA_*) > .env (ZAYRA_*) > config.json > defaults.

Providers

config.set("providers.groq.enabled", true);

Supports Groq, Gemini, OpenAI, OpenRouter, and Local Models out of the box, plus any custom provider — just use whatever name you like under providers.<name>.

import { KNOWN_PROVIDER_NAMES, isKnownProvider } from "zayra-config";

isKnownProvider("groq");     // true
isKnownProvider("mistral");  // false — still a perfectly valid custom provider

ZAYRA should automatically select available AI systems (spec) is supported as read-only reporting — zayra-config tells you what's configured and available; the actual choosing is zayra-ai-orchestrator's job:

config.getAvailableProviders(); // e.g. ["groq"] — enabled AND has an API key (local never needs one)

API keys — never stored in config.json

Provider API keys are read live from the environment by convention (<PROVIDER_NAME>_API_KEY), and are never part of the config tree that save() writes:

# .env
GROQ_API_KEY=your-key-here
GEMINI_API_KEY=your-key-here

config.getProviderApiKey("groq");      // reads GROQ_API_KEY live, every call
config.getAllProviderApiKeys();         // { groq: "...", ... } — only providers with a key actually set
JSON.stringify(config.getAll());        // never contains an API key, guaranteed

Custom providers follow the same convention — a provider named "mistral" looks for MISTRAL_API_KEY.

Model selection settings

config.get("models.autoSelect");     // true
config.get("models.selectionMode");  // "smart"

Recognized selectionMode values: smart, manual, fastest, cheapest. Like providers, this is configuration only — an AI orchestrator reads these settings to decide how to pick a model; zayra-config never picks one itself.

Plugins

config.get("plugins.enabled");    // true
config.get("plugins.installed");  // []

User preferences

config.get("user.theme");          // "dark"
config.get("user.language");       // "en"
config.get("user.personality");    // "default"
config.get("user.responseStyle");  // "balanced"
config.get("user.privacy");        // "standard"

Security settings

Declarative only — other packages (zayra-core, zayra-tools, etc.) are expected to read and enforce these; zayra-config does not enforce anything itself.

config.get("security.permissions.allowFileAccess");       // false
config.get("security.secretManagement.source");            // "env"
config.get("security.accessControl.requireAuth");           // false

Reading, updating, removing

config.get("ai.provider", "fallback-value");
config.has("ai.provider");
config.getAll();

config.set("user.theme", "light");
config.update({ ai: { provider: "gemini" } }); // deep-merge
config.remove("user.language");                  // NEW in v0.0.2 — deletes a key

await config.save(); // writes config.json (never includes API keys)

Validation

import { ConfigManager, createDefaultValidator } from "zayra-config";

const config = new ConfigManager({ validator: createDefaultValidator() });
await config.load();
config.validate(); // checks provider config, model config, plugin config, security config

createDefaultValidator() bundles the built-in rule-sets for providers, models, plugins, and security. You can still add your own rules on top with config.addValidationRule(rule), or build a validator from scratch with new ConfigValidator([...]) as in v0.0.1.

Migrating an old config.json programmatically

If you're managing your own config.json (outside of the automatic migration script), you can migrate its shape directly:

import { migrateLegacyConfigShape } from "zayra-config";

const oldConfig = JSON.parse(await fs.readFile("config.json", "utf-8"));
const migrated = migrateLegacyConfigShape(oldConfig);
await fs.writeFile("config.json", JSON.stringify(migrated, null, 2));

This relocates a bare top-level theme into user.theme, adds every new v0.0.2 section with its defaults, and preserves anything else you'd already customized (including keys it doesn't recognize). Safe to run more than once — it's idempotent.

Errors

• ConfigError — base error class; load/save/serialization failures.
• ValidationError — extends ConfigError; thrown by ConfigValidator/config.validate(), carries err.issues.

Security rules

zayra-config never stores API keys, passwords, or tokens inside source code or config.json. Provider API keys always come from the environment and are structurally kept out of the mergeable/persistable config tree — there's no "strip secrets before saving" step because secrets never enter that tree in the first place.

Migration script

scripts/update-v0.0.2.js performs the 0.0.1 → 0.0.2 upgrade automatically:

1. Detects the current version from package.json.
2. Creates a timestamped backup (backup/<timestamp>/) of package.json, src/, test/, README.md, and config files (.env, .env.example, config.json) that exist.
3. Writes the new/updated src/*.js files.
4. If a config.json exists in the package root (or a path passed via --config=<path>), migrates its contents to the new shape using migrateLegacyConfigShape().
5. Updates package.json's version to 0.0.2.
6. Verifies the migration by actually importing the new package, loading and validating a config end-to-end, and confirming provider API key isolation.
7. If any step fails, automatically restores everything from the backup and exits with an error.

node scripts/update-v0.0.2.js
# or, to also migrate a config.json living elsewhere:
node scripts/update-v0.0.2.js --config=/path/to/your/config.json

After a successful migration, run npm test, then npm publish when ready (the version is already bumped to 0.0.2).

Project structure

zayra-config/
  src/
    index.js           # public entry point
    manager.js          # ConfigManager class
    loader.js            # source merging, config.json read/write, legacy migration
    validator.js          # ConfigValidator + createDefaultValidator
    environment.js         # ZAYRA_* mapping + provider API key lookup
    providers.js            # multi-provider config (Groq/Gemini/OpenAI/OpenRouter/Local/custom)
    models.js                # model selection settings
    security.js                # permissions / secretManagement / accessControl
    errors.js                   # ConfigError, ValidationError
  scripts/
    update-v0.0.2.js             # automatic migration script
  backup/                         # created by the migration script
  package.json
  README.md

Compatibility

Designed to work with zayra-core, zayra-ai-orchestrator, zayra-provider, and zayra-plugins.

License

MIT