@techery/asset-vision

File upload processing pipeline with AI-powered image recognition for edge runtimes.

Features

• 🚀 Edge Runtime Compatible - Works on Cloudflare Workers, Fastly Compute, and Node.js 20+
• 🔌 Plugin Architecture - Extensible storage and queue adapters
• 🤖 AI Vision Processing - Built-in Gemini Flash integration with structured output
• 📝 Type-Safe Schemas - Zod schemas for AI responses
• ⚡ Async Processing - Queue-based background processing
• 🎯 Framework Agnostic - Use with Hono, Express, or any framework
• 🔒 Stateless Design - JWT-based slot tracking, no database required
• 🎨 Custom Schemas - Define your own AI response structures

Installation

npm install @techery/asset-vision zod

Quick Start

1. Configure AssetVision

import { AssetVision } from "@techery/asset-vision";
import { foodRecognitionSchema, foodRecognitionPrompt } from "@techery/asset-vision/examples";

const assetVision = new AssetVision({
  storage: {
    type: "r2",
    bucket: env.ASSETS_BUCKET,
    publicUrlBase: "https://assets.example.com",
    pathPrefix: "uploads/",
  },
  queue: {
    type: "cloudflare-queues",
    queue: env.PROCESSING_QUEUE,
  },
  vision: {
    provider: "gemini",
    model: "gemini-2.0-flash",
    apiKey: env.GOOGLE_API_KEY,
    responseSchema: foodRecognitionSchema,
    systemPrompt: foodRecognitionPrompt,
  },
  upload: {
    maxFileSizeBytes: 5 * 1024 * 1024,
    allowedMimeTypes: ["image/jpeg", "image/png", "image/webp"],
  },
  callbacks: {
    onProcessingComplete: async (result) => {
      // Save to database, send notification, etc.
      console.log("Analysis complete:", result.aiAnalysis);
    },
    onProcessingError: async (error) => {
      console.error("Processing failed:", error);
    },
  },
}, "https://api.yourapp.com");

2. Request Upload Slot

// Backend API endpoint
app.post("/api/upload/slot", async (req, res) => {
  const slot = await assetVision.requestSlot({
    mimeType: req.body.mimeType,
    metadata: { userId: req.user.id },
  });

  res.json(slot);
  // Returns:
  // {
  //   id: "abc123",
  //   uploadUrl: "https://storage.../signed-url",
  //   publicUrl: "https://cdn.../file.jpg",
  //   successUrl: "https://api.../success/jwt-token",
  //   cancelUrl: "https://api.../cancel/jwt-token",
  //   expiresAt: "2024-12-19T12:00:00.000Z"
  // }
});

3. Frontend Upload

// Frontend: Upload directly to storage
const response = await fetch("/api/upload/slot", {
  method: "POST",
  body: JSON.stringify({ mimeType: "image/jpeg" }),
});
const slot = await response.json();

// Upload file directly to storage (bypasses backend)
await fetch(slot.uploadUrl, {
  method: "PUT",
  body: imageFile,
  headers: { "Content-Type": "image/jpeg" },
});

// Notify backend that upload succeeded
await fetch(slot.successUrl, { method: "POST" });

4. Process in Queue

// Cloudflare Worker queue consumer
export default {
  async queue(batch, env) {
    const assetVision = new AssetVision(config, "https://api.yourapp.com");

    for (const message of batch.messages) {
      try {
        const job = message.body;
        await assetVision.processJob(job);
        message.ack();
      } catch (error) {
        console.error("Processing failed:", error);
        message.retry();
      }
    }
  },
};

How It Works

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│ Request │ ──> │ Upload  │ ──> │ Success │ ──> │  Queue  │ ──> │   AI    │
│  Slot   │     │   to    │     │Callback │     │ Process │     │Analysis │
│         │     │ Storage │     │         │     │         │     │         │
└─────────┘     └─────────┘     └─────────┘     └─────────┘     └─────────┘

1. Frontend requests upload slot with signed URL
2. Frontend uploads directly to storage (R2/S3/GCS)
3. Frontend calls success callback URL
4. Backend enqueues processing job
5. Worker processes job with AI vision
6. Results saved and callback triggered

Custom AI Schemas

Define your own analysis schema:

import { z } from "zod";

const documentSchema = z.object({
  documentType: z.enum(["invoice", "receipt", "contract", "id_card"]),
  extractedText: z.string(),
  confidence: z.number().min(0).max(1),
  fields: z.array(z.object({
    name: z.string(),
    value: z.string(),
    confidence: z.number(),
  })),
});

const assetVision = new AssetVision({
  vision: {
    provider: "gemini",
    model: "gemini-2.0-flash",
    apiKey: env.GOOGLE_API_KEY,
    responseSchema: documentSchema,
    systemPrompt: "Extract text and fields from this document image.",
  },
  // ... other config
}, baseUrl);

Examples

Food Recognition

import { foodRecognitionSchema, foodRecognitionPrompt } from "@techery/asset-vision/examples";

// Built-in schema for nutritional analysis:
// - Food identification
// - Calorie estimation
// - Macronutrients (protein, carbs, fats)
// - Ingredients/components
// - Barcode detection
// - Image quality assessment

Cloudflare Worker

Full example in src/examples/cloudflare-worker/index.ts

Documentation

• Full Documentation
• API Reference
• Configuration Guide
• Examples

Architecture

• Stateless: Upload slot state encoded in JWT tokens
• Plugin-based: Easy to extend with new storage/queue providers
• Type-safe: Full TypeScript support with Zod schemas
• Edge-optimized: Works on Cloudflare Workers and similar platforms

Roadmap

• [ ] S3 storage plugin
• [ ] GCS storage plugin
• [ ] BullMQ queue adapter
• [ ] Claude vision processor
• [ ] Retry logic with exponential backoff
• [ ] Multi-image batch processing
• [ ] Streaming AI responses

Contributing

Contributions welcome! This package is maintained by Techery for internal use but open to community improvements.

License

Copyright (c) 2024 Techery. All rights reserved.

This software is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.