nexus-ai-pro 1.0.0 → 1.1.0

package/API_STABILITY.md

@@ -1,10 +1,13 @@
 # API Stability Policy
 
-This policy describes compatibility guarantees for `nexus-ai-pro` beginning with version 0.9.0.
+This policy describes compatibility guarantees for `nexus-ai-pro`. The 1.x compatibility guarantees
+apply beginning with version 1.0.0.
 
 ## Release stages
 
-The package is pre-1.0. Minor releases may contain breaking changes when they are necessary, but those changes will be called out in the changelog with migration guidance. Patch releases are intended to remain backward compatible.
+The package follows semantic versioning. Within the 1.x line, incompatible changes to stable public
+APIs require a major release. Minor releases may add backward-compatible features, and patch releases
+are intended to remain backward compatible.
 
 The following surfaces are public and covered by this policy:
 
@@ -33,11 +36,12 @@ explicit `realtime/session`, `realtime/tools`, `realtime/conversation`, `realtim
 normalized event names, configuration fields, and conversation/export shapes follow the same patch
 compatibility rules as the rest of the package.
 
-The realtime surface is still pre-1.0. Provider-specific wire events returned by `openai-events`, values
+The realtime surface follows the 1.x compatibility rules for its normalized public API. Provider-specific
+wire events returned by `openai-events`, values
 under `raw`, SDP/ICE behavior, and upstream model or voice availability are controlled by the provider
 and are not normalized compatibility guarantees. New normalized event variants or optional metrics may
-be added in a minor release. A necessary incompatible change during 0.x will be documented in a minor
-release with migration guidance.
+be added in a minor release. Incompatible normalized API changes require a major release unless an urgent
+security fix makes preserving the old behavior unsafe.
 
 Platform interfaces for WebRTC and WebSocket are structural so applications can inject browser, server,
 mobile, or test adapters without a framework dependency. A documented structural member is public;
@@ -48,8 +52,22 @@ turn-oriented transcription/completion/speech workflow. `RealtimeSession` owns a
 live events, interruption, and normalized realtime conversation state. Neither is a compatibility alias
 for the other.
 
+## Image API stage
+
+The `nexus-ai-pro/images` family is experimental in production-readiness, but published normalized
+types, manager methods, operation events, and explicit subpath exports still follow the 1.x semantic
+versioning rules. The experimental label does not permit an incompatible minor or patch release.
+
+Provider payloads under `raw`, provider-specific error metadata, temporary delivery URLs, upstream model
+availability, and generative output are not normalized compatibility guarantees. The current local
+operation handle is process-bound and does not promise durable recovery, distributed cancellation, or
+exactly-once provider execution. Those capabilities will use additive adapters and contracts when added.
+`MemoryAssetStore` is likewise process-local and does not promise cross-process durability or shared
+tenant state.
+
 ## Deprecation process
 
-Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. During the 0.x series, removal will not normally occur earlier than the next minor release. After 1.0, removals will be reserved for major releases, except when an urgent security issue requires otherwise.
+Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals
+are reserved for major releases, except when an urgent security issue requires otherwise.
 
 Report accidental compatibility regressions through the project issue tracker. Security issues should follow [SECURITY.md](./SECURITY.md).

package/CHANGELOG.md

@@ -1,11 +1,29 @@
 # Changelog
 
-Notable changes to this project are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and releases use semantic versioning while accounting for the pre-1.0 stability policy.
+Notable changes to this project are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and releases use semantic versioning.
 
 ## [Unreleased]
 
 ### Added
 
+- An experimental provider-neutral image operation family with portable asset locations,
+  `ImageManager`, generation/editing, strict capability negotiation, runtime provider registration,
+  visual-safety hooks, and cancellable local operation handles.
+- Opt-in `images`, `images/assets`, `images/mock`, and `images/openai` subpaths with a deterministic
+  mock provider and an OpenAI Image API adapter for one-shot generation and reference-based editing.
+- An image-provider conformance harness covering normalized assets, metadata, generation, editing, and
+  pre-aborted calls.
+- A bounded tenant-isolated `MemoryAssetStore` with retention, defensive byte copies, computed SHA-256
+  checksums, capacity enforcement, and optional HTTP(S) signing.
+
+### Changed
+
+- Reconciled the changelog and API stability policy with the tagged 1.0.0 release.
+
+## [1.0.0] - 2026-07-17
+
+### Added
+
 - An opt-in realtime package family with `realtime`, `realtime/session`, `realtime/tools`,
   `realtime/conversation`, provider transport, server-helper, and deterministic mock subpaths. Realtime
   code is not added to the root or batch voice import graph.
@@ -55,5 +73,6 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 - URL fetching rejects unsafe private-network targets and limits response reads.
 - CLI and audit findings no longer disclose detected secret values.
 
-[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v0.9.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/releases/tag/v1.0.0
 [0.9.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/releases/tag/v0.9.0

package/README.md

@@ -7,7 +7,7 @@ Use the whole pipeline for production AI features, or turn pieces off when you o
 - NPM: https://www.npmjs.com/package/nexus-ai-pro
 - GitHub: https://github.com/mkhitar-abrahamyan/nexus-ai
 - Full technical notes and manual test cases: [NEXUS.md](./NEXUS.md)
-- Planned image generation and infrastructure work: [ROADMAP.md](./ROADMAP.md)
+- Image generation status and remaining infrastructure work: [ROADMAP.md](./ROADMAP.md)
 
 ## Install
 
@@ -307,6 +307,63 @@ const response = await ai.completeVerified(
 );
 ```
 
+## Image Generation and Editing (Experimental)
+
+Image operations use a separate provider-neutral manager because generated assets have different
+capabilities, delivery modes, safety checks, and lifecycles from text completions.
+
+```ts
+import { NexusAI } from 'nexus-ai-pro';
+import { OpenAIImageProvider } from 'nexus-ai-pro/images/openai';
+
+const openaiImages = new OpenAIImageProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+});
+
+const mediaAi = new NexusAI({
+  providers: {},
+  images: {
+    defaultProvider: 'openai',
+    providers: { openai: openaiImages },
+  },
+});
+
+const image = await mediaAi.images.generate({
+  model: 'auto',
+  prompt: 'A clean product photograph of a red mechanical keyboard',
+  dimensions: { width: 1536, height: 1024 },
+  quality: 'high',
+  delivery: { kind: 'bytes', format: 'png' },
+});
+
+console.log(image.assets[0]?.location);
+```
+
+`ImageProvider` is independent from completion providers. Explicit options are negotiated against the
+selected provider's declared capabilities, so unsupported formats, delivery kinds, masks, seeds, or
+dimensions fail before a provider call. The OpenAI adapter supports one-shot generation and
+reference-based editing through byte assets. Masked OpenAI edits remain disabled until a transformer can
+verify dimensions and convert the neutral mask contract to OpenAI's alpha-channel semantics.
+
+Use `submit()` for a cancellable local operation handle with replayable lifecycle events:
+
+```ts
+const operation = mediaAi.images.submit('generate', {
+  prompt: 'A minimal blue geometric poster',
+  delivery: { kind: 'bytes', format: 'png' },
+});
+
+for await (const event of operation.events()) {
+  console.log(event.type);
+}
+```
+
+For deterministic tests, register `MockImageProvider` from `nexus-ai-pro/images/mock`. The current
+`submit()` handle is in-process; durable leases, recovery, distributed deduplication, and webhooks remain
+future infrastructure work. `nexus-ai-pro/images/assets` includes a bounded, tenant-isolated
+`MemoryAssetStore` for local development and single-process workloads; it computes SHA-256 checksums,
+copies bytes at its boundaries, enforces retention and capacity, and never silently evicts live assets.
+
 ## Voice Integrations
 
 Voice support is optional and split into small imports.
@@ -892,6 +949,10 @@ import { ContextWindowManager } from 'nexus-ai-pro/context';
 import { guardrailPolicy } from 'nexus-ai-pro/security';
 import { RedisCacheAdapter } from 'nexus-ai-pro/cache';
 import { DeepSeekProvider } from 'nexus-ai-pro/providers/deepseek';
+import { ImageManager } from 'nexus-ai-pro/images';
+import { MemoryAssetStore } from 'nexus-ai-pro/images/assets';
+import { MockImageProvider } from 'nexus-ai-pro/images/mock';
+import { OpenAIImageProvider } from 'nexus-ai-pro/images/openai';
 import { createRealtimeSession } from 'nexus-ai-pro/realtime/session';
 import { OpenAIWebRTCTransport } from 'nexus-ai-pro/realtime/openai-webrtc';
 ```
@@ -946,10 +1007,10 @@ npm run test:conformance:real
 
 ## Roadmap
 
-The next recommended feature family is first-class image generation and editing through a
-provider-neutral `ImageManager`, portable asset types, durable operation handles, visual safety,
-asset storage, and media-specific evaluations. The design and prioritized infrastructure backlog
-are in [ROADMAP.md](./ROADMAP.md).
+The experimental image foundation now includes portable asset types, `ImageManager`, provider
+capability negotiation, local operation handles, visual-safety hooks, deterministic conformance, and an
+opt-in OpenAI adapter. Durable operations, production asset storage, additional providers, and
+media-specific evaluations remain planned in [ROADMAP.md](./ROADMAP.md).
 
 ## Production Notes
 

package/ROADMAP.md

@@ -36,7 +36,23 @@ Current limitations are intentional and should remain visible:
 - Realtime video tracks, SIP transports, durable cost accounting beyond the configurable local estimate,
   and a published latency benchmark methodology remain follow-on work.
 
-## Recommended next release: first-class image generation
+## Current next-release work: first-class image generation
+
+The experimental foundation is now implemented in the current development line:
+
+- portable byte, URL, and stored asset locations plus image request/result, usage, safety, provenance,
+  provider-call context, and operation-handle types;
+- a provider-neutral `ImageManager` with generation, editing, provider registration, strict capability
+  negotiation, visual-safety hooks, and cancellable in-process submissions;
+- a deterministic network-free mock and a parallel image-provider conformance harness;
+- an opt-in OpenAI Image API adapter for one-shot generation and reference-based editing;
+- a bounded tenant-aware in-memory asset store with retention, defensive byte copies, computed SHA-256
+  checksums, capacity rejection, and optional signed-URL integration.
+
+This surface remains experimental. OpenAI masks are intentionally disabled until a transformer can
+verify dimensions and convert neutral mask polarity into provider alpha semantics. Durable operations,
+filesystem/S3-compatible asset stores, a second cloud provider, ComfyUI, and media evaluation are still
+required before promotion.
 
 Image generation should be a separate operation family rather than another variation of
 `complete()`. Text completions and generated assets have different request shapes, response

package/dist/core/config-builder.d.ts

@@ -1,6 +1,7 @@
 import { NexusAI } from './nexus.js';
 import type { AnthropicProviderConfig, AuditLogConfig, AzureOpenAIProviderConfig, CacheConfig, CohereProviderConfig, CostBudgetConfig, CustomProviderConfig, DeepSeekProviderConfig, GoogleProviderConfig, GroqProviderConfig, LMStudioProviderConfig, LlamaCppProviderConfig, LoggerConfig, MistralProviderConfig, NexusAIConfig, OllamaProviderConfig, OpenAIProviderConfig, OpenRouterProviderConfig, ProvidersConfig, RateLimitConfig, ResponseFormatConfig, RetryConfig, RoutingConfig, RoutingStrategy } from '../types/config.js';
 import type { ContextWindowConfig } from '../types/context-window.js';
+import type { ImageConfig } from '../types/images.js';
 import type { SecurityConfig, SecurityLevel } from '../types/security.js';
 import type { TokenOptimizerConfig } from '../types/optimizer.js';
 import type { PipelineConfig } from '../pipeline/types.js';
@@ -53,6 +54,8 @@ export declare class NexusConfigBuilder {
     security(config: SecurityLevel | SecurityConfig): this;
     /** Sets context-window compaction behavior. */
     contextWindow(config: ContextWindowConfig): this;
+    /** Sets image-provider defaults and registrations. */
+    images(config: ImageConfig): this;
     /** Sets token optimization behavior. */
     tokenOptimizer(config: TokenOptimizerConfig): this;
     /** Sets exact, semantic, or hybrid cache behavior. */

package/dist/core/config-builder.js

@@ -98,6 +98,11 @@ export class NexusConfigBuilder {
         this.config.contextWindow = config;
         return this;
     }
+    /** Sets image-provider defaults and registrations. */
+    images(config) {
+        this.config.images = config;
+        return this;
+    }
     /** Sets token optimization behavior. */
     tokenOptimizer(config) {
         this.config.tokenOptimizer = config;

package/dist/core/nexus.d.ts

@@ -4,10 +4,12 @@ import type { NexusPlan } from '../types/planning.js';
 import type { NexusResponse, NexusStream } from '../types/response.js';
 import type { AgentConfig, AgentResult } from '../types/agent.js';
 import type { SpeechRequest, SpeechResponse, TranscriptionRequest, TranscriptionResponse, VoiceProvider, VoiceSessionConfig, VoiceTurnRequest, VoiceTurnResponse } from '../types/voice.js';
+import type { ImageProvider } from '../types/images.js';
 import type { CreateCallRequest, CreateCallResponse, TelephonyMediaStreamEvent, TelephonyOutboundAudioMessage, TelephonyProvider, TelephonyResponseRequest, TelephonyWebhookResponse, TelephonyWebhookValidationRequest } from '../types/telephony.js';
 import type { PipelineStep } from '../pipeline/types.js';
 import type { BaseProvider } from '../providers/base.js';
 import { type VoiceSession } from '../voice/index.js';
+import { ImageManager } from '../images/manager.js';
 import { type VerificationOptions } from '../hallucination/verification.js';
 import { type SelfConsistencyOptions } from '../hallucination/consistency.js';
 import { type BatchOptions, type BatchItemResult } from '../jobs/batch.js';
@@ -20,6 +22,8 @@ import { type SummarizeVerifyFormatOptions, type WorkflowResult } from '../workf
  * Use `new NexusAI(config)` when you want full control, or `createNexus()` for the beginner shorthand.
  */
 export declare class NexusAI {
+    /** Provider-neutral image generation and editing operations. */
+    readonly images: ImageManager;
     private config;
     private providers;
     private router;
@@ -112,18 +116,24 @@ export declare class NexusAI {
      * Registers a custom voice provider at runtime.
      */
     registerVoiceProvider(name: string, provider: VoiceProvider): this;
+    /**
+     * Registers a custom image provider at runtime.
+     */
+    registerImageProvider(name: string, provider: ImageProvider): this;
     /**
      * Registers a custom telephony provider at runtime.
      */
     registerTelephonyProvider(name: string, provider: TelephonyProvider): this;
     hasProvider(name: string): boolean;
     hasVoiceProvider(name: string): boolean;
+    hasImageProvider(name: string): boolean;
     hasTelephonyProvider(name: string): boolean;
     /**
      * Lists configured text providers.
      */
     listProviders(): string[];
     listVoiceProviders(): string[];
+    listImageProviders(): string[];
     listTelephonyProviders(): string[];
     /**
      * Adds a custom pipeline step.

package/dist/core/nexus.js

@@ -15,6 +15,7 @@ import { Logger } from '../utils/logger.js';
 import { SecurityPipeline } from '../security/index.js';
 import { ContextWindowManager } from '../context/index.js';
 import { VoiceManager } from '../voice/index.js';
+import { ImageManager } from '../images/manager.js';
 import { TelephonyManager } from '../telephony/index.js';
 import { TokenOptimizer } from '../optimizer/index.js';
 import { AgentLoop } from '../agent/loop.js';
@@ -41,6 +42,8 @@ import { summarizeVerifyFormat } from '../workflow/chains.js';
  * Use `new NexusAI(config)` when you want full control, or `createNexus()` for the beginner shorthand.
  */
 export class NexusAI {
+    /** Provider-neutral image generation and editing operations. */
+    images;
     config;
     providers = new Map();
     router = new Router();
@@ -73,6 +76,7 @@ export class NexusAI {
         this.security = new SecurityPipeline(this.config.security || 'standard');
         this.contextWindow = new ContextWindowManager(this.config.contextWindow || {});
         this.voiceManager = new VoiceManager(this.config.voice || {});
+        this.images = new ImageManager(this.config.images || {});
         this.telephonyManager = new TelephonyManager(this.config.telephony || {});
         this.optimizer = new TokenOptimizer(this.config.tokenOptimizer || {});
         this.cache = new MemoryCache(this.config.cache?.maxEntries || 500);
@@ -453,6 +457,13 @@ export class NexusAI {
         this.voiceManager.registerProvider(name, provider);
         return this;
     }
+    /**
+     * Registers a custom image provider at runtime.
+     */
+    registerImageProvider(name, provider) {
+        this.images.registerImageProvider(name, provider);
+        return this;
+    }
     /**
      * Registers a custom telephony provider at runtime.
      */
@@ -466,6 +477,9 @@ export class NexusAI {
     hasVoiceProvider(name) {
         return this.voiceManager.hasProvider(name);
     }
+    hasImageProvider(name) {
+        return this.images.hasImageProvider(name);
+    }
     hasTelephonyProvider(name) {
         return this.telephonyManager.hasProvider(name);
     }
@@ -478,6 +492,9 @@ export class NexusAI {
     listVoiceProviders() {
         return this.voiceManager.listProviders();
     }
+    listImageProviders() {
+        return this.images.listImageProviders();
+    }
     listTelephonyProviders() {
         return this.telephonyManager.listProviders();
     }

package/dist/images/assets.d.ts

@@ -0,0 +1,115 @@
+import type { AssetBytesLocation, AssetDescriptor, AssetInput, AssetProvenance } from '../types/images.js';
+/** An asset input whose payload is already available locally as bytes. */
+export interface ByteAssetInput extends Omit<AssetInput, 'location'> {
+    location: AssetBytesLocation;
+}
+/** A retrieved asset descriptor whose byte payload is available to the caller. */
+export interface ByteAssetDescriptor extends Omit<AssetDescriptor, 'location'> {
+    location: AssetBytesLocation;
+}
+export interface AssetPutOptions {
+    /** Tenant that owns the asset. This value is required for every later access. */
+    tenantId: string;
+    provenance: AssetProvenance;
+    width?: number;
+    height?: number;
+    /** Relative retention period. Mutually exclusive with `expiresAt`. */
+    ttlSeconds?: number;
+    /** Absolute retention deadline. Mutually exclusive with `ttlSeconds`. */
+    expiresAt?: Date | string;
+}
+export interface AssetStat {
+    assetId: string;
+    tenantId: string;
+    /** Metadata-only descriptor. Its location points back to this store, not to the byte payload. */
+    descriptor: AssetDescriptor;
+    createdAt: string;
+    expiresAt?: string;
+}
+export interface AssetSignOptions {
+    /** Requested signed-URL lifetime. Enforcement is delegated to the configured signer. */
+    expiresInSeconds?: number;
+}
+export interface AssetSignerContext extends AssetStat {
+    now: string;
+    expiresInSeconds?: number;
+}
+export type AssetSigner = (context: AssetSignerContext) => string | URL | Promise<string | URL>;
+export type AssetStoreResult<T> = T | Promise<T>;
+/**
+ * Provider-neutral asset persistence contract.
+ *
+ * A store must treat a missing asset and an asset owned by another tenant identically. Implementations
+ * may complete synchronously or asynchronously so the same contract can cover memory and remote stores.
+ */
+export interface AssetStore {
+    put(input: ByteAssetInput, options: AssetPutOptions): AssetStoreResult<AssetStat>;
+    get(assetId: string, tenantId: string): AssetStoreResult<ByteAssetDescriptor | undefined>;
+    stat(assetId: string, tenantId: string): AssetStoreResult<AssetStat | undefined>;
+    delete(assetId: string, tenantId: string): AssetStoreResult<true | undefined>;
+    sign(assetId: string, tenantId: string, options?: AssetSignOptions): AssetStoreResult<string | undefined>;
+    purgeExpired(): AssetStoreResult<number>;
+}
+export interface MemoryAssetStoreOptions {
+    maxEntries?: number;
+    maxTotalBytes?: number;
+    maxAssetBytes?: number;
+    defaultTtlSeconds?: number;
+    createAssetId?: () => string;
+    now?: () => Date;
+    signer?: AssetSigner;
+}
+export interface MemoryAssetStoreSnapshot {
+    entries: number;
+    totalBytes: number;
+    maxEntries: number;
+    maxTotalBytes: number;
+    maxAssetBytes: number;
+}
+export declare class AssetStoreError extends Error {
+    readonly code: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: string, cause?: unknown | undefined);
+}
+export declare class AssetStoreValidationError extends AssetStoreError {
+    constructor(message: string, cause?: unknown);
+}
+export type AssetCapacityConstraint = 'maxEntries' | 'maxTotalBytes' | 'maxAssetBytes';
+export declare class AssetStoreCapacityError extends AssetStoreError {
+    readonly constraint: AssetCapacityConstraint;
+    readonly maximum: number;
+    readonly current: number;
+    readonly requested: number;
+    constructor(constraint: AssetCapacityConstraint, maximum: number, current: number, requested: number);
+}
+export declare class AssetStoreSigningError extends AssetStoreError {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Process-local, bounded asset storage. Capacity exhaustion rejects the write; live entries are never
+ * silently evicted. Expired entries are purged before capacity and access decisions.
+ */
+export declare class MemoryAssetStore implements AssetStore {
+    private readonly entries;
+    private readonly maxEntries;
+    private readonly maxTotalBytes;
+    private readonly maxAssetBytes;
+    private readonly defaultTtlSeconds?;
+    private readonly createAssetId;
+    private readonly clock;
+    private readonly signer?;
+    private totalBytes;
+    constructor(options?: MemoryAssetStoreOptions);
+    put(input: ByteAssetInput, options: AssetPutOptions): AssetStat;
+    get(assetId: string, tenantId: string): ByteAssetDescriptor | undefined;
+    stat(assetId: string, tenantId: string): AssetStat | undefined;
+    delete(assetId: string, tenantId: string): true | undefined;
+    sign(assetId: string, tenantId: string, options?: AssetSignOptions): Promise<string | undefined>;
+    purgeExpired(): number;
+    snapshot(): MemoryAssetStoreSnapshot;
+    private assertCapacity;
+    private ownedEntry;
+    private purgeExpiredAt;
+    private removeEntry;
+    private nowMs;
+}