henri-photo 2.0.0

package/README.md

@@ -0,0 +1,108 @@
+# henri-photo
+
+Photographic intelligence via [Model Context Protocol](https://modelcontextprotocol.io). HENRI analyzes, curates, and critiques photographs with museum-curator eye.
+
+Named after Henri Cartier-Bresson. Reads through formal analysis, historical literacy, and curatorial judgment.
+
+## Install
+
+Add to your Claude Code MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "henri": {
+      "command": "npx",
+      "args": ["henri-photo", "--dir", "/path/to/your/henri-data"]
+    }
+  }
+}
+```
+
+Or run directly:
+
+```bash
+npx henri-photo --dir ~/.henri
+```
+
+## Setup
+
+HENRI reads from a data directory containing your analyzed photo archive:
+
+```
+~/.henri/
+  manifest-v2.json      # Image manifest with analysis data
+  collections/          # Curated thematic collections
+  essays/              # Visual essays (critical prose)
+  pairs.json           # Cross-body visual pairings
+  embeddings/          # CLIP embeddings, color, scene data
+  eye/                 # Secondary camera manifest
+```
+
+To build this data, use the HENRI CLI to analyze your photos:
+
+```bash
+# Clone the repo for full CLI access
+git clone https://github.com/sethgoldstein/henri
+cd henri && npm install
+
+# Set your data directory and photo source
+export HENRI_DIR=~/.henri
+export HENRI_PHOTOS=~/Pictures/photos
+
+# Analyze your archive (~$0.03/image via Claude API)
+npm run henri -- analyze --batch
+
+# Generate collections and essays
+npm run henri -- curate
+npm run henri -- collections --propose
+npm run henri -- essay -c <collection-id>
+```
+
+## MCP Tools
+
+15 tools available to any MCP-compatible client:
+
+| Tool | Description |
+|------|-------------|
+| `search_archive` | Natural language search across all analysis axes |
+| `get_image_analysis` | Full 5-axis analysis for a specific image |
+| `list_collections` | All curated thematic collections |
+| `get_collection` | Collection details with thesis and sequence |
+| `get_daily_signal` | Daily selects, cross-body echoes, rising images |
+| `get_tier_breakdown` | Archive quality tiers (exhibition through discard) |
+| `get_cross_body_pairs` | Same-day echoes across camera bodies |
+| `get_essay` | Read a visual essay |
+| `list_essays` | All available essays |
+| `search_by_color` | Find images by color, harmony, temperature |
+| `get_shooting_patterns` | Temporal patterns, golden hour, burst groups |
+| `find_similar` | CLIP-based visual similarity search |
+| `get_scene_breakdown` | Scene types, indoor/outdoor, objects, materials |
+| `get_people` | Face detection, distinct people, co-occurrences |
+| `get_style_clusters` | Visual style clusters and near-duplicates |
+
+## The 5-Axis Framework
+
+Every image is scored across five axes:
+
+- **Formal** -- composition, light, spatial organization, color relationships
+- **Technical** -- sharpness, exposure, focus decisions, processing
+- **Semantic** -- subject, narrative, emotional register, cultural context
+- **Historical** -- photographic traditions, references, lineage
+- **Curatorial** -- tier ranking (exhibition/portfolio/strong/study/discard), 0-100 score
+
+## Pricing
+
+- Analysis: ~$0.03/image (Claude API cost)
+- Essay generation: ~$0.07/essay
+- MCP server: free (reads pre-computed data)
+
+## Links
+
+- [henri.photos](https://henri.photos) -- landing page and case studies
+- [henri.photos/ask](https://henri.photos/ask) -- chat with HENRI
+- [henri.photos/hire](https://henri.photos/hire) -- get started
+
+## License
+
+MIT

package/dist/analyze/batch-runner.d.ts

@@ -0,0 +1,10 @@
+export interface BatchOptions {
+    concurrency: number;
+    costLimit: number;
+    resume: boolean;
+    dryRun: boolean;
+    singleImage?: string;
+    useThumbnails: boolean;
+    model: string;
+}
+export declare function runBatch(opts: BatchOptions): Promise<void>;

package/dist/analyze/batch-runner.js

@@ -0,0 +1,144 @@
+import path from 'path';
+import { PATHS } from '../lib/config.js';
+import { readJson, writeJson, log } from '../lib/state.js';
+import { loadSiteManifest, saveHenriManifest } from '../lib/manifest.js';
+import { analyzeImage } from './vision-analyzer.js';
+function loadProgress() {
+    return readJson(PATHS.analysisProgress, {
+        completed: {},
+        totalCostUsd: 0,
+        totalInputTokens: 0,
+        totalOutputTokens: 0,
+        lastUpdated: new Date().toISOString(),
+        errors: [],
+    });
+}
+function saveProgress(progress) {
+    progress.lastUpdated = new Date().toISOString();
+    writeJson(PATHS.analysisProgress, progress);
+}
+export async function runBatch(opts) {
+    const siteManifest = loadSiteManifest();
+    const progress = opts.resume ? loadProgress() : {
+        completed: {},
+        totalCostUsd: 0,
+        totalInputTokens: 0,
+        totalOutputTokens: 0,
+        lastUpdated: new Date().toISOString(),
+        errors: [],
+    };
+    // Determine which images to process
+    let images = siteManifest.images;
+    if (opts.singleImage) {
+        const target = opts.singleImage.endsWith('.webp') ? opts.singleImage : `${opts.singleImage}.webp`;
+        images = images.filter(img => img.filename === target);
+        if (images.length === 0) {
+            log(`image not found: ${opts.singleImage}`);
+            return;
+        }
+    }
+    // Filter already completed
+    const pending = images.filter(img => !progress.completed[img.filename]);
+    log(`batch: ${pending.length} pending, ${Object.keys(progress.completed).length} completed, $${progress.totalCostUsd.toFixed(2)} spent`);
+    if (opts.dryRun) {
+        log('dry run — showing first image prompt:');
+        if (pending.length > 0) {
+            const img = pending[0];
+            const { buildSystemPrompt, buildUserPrompt } = await import('./prompt.js');
+            console.log('\n--- SYSTEM PROMPT ---');
+            console.log(buildSystemPrompt());
+            console.log('\n--- USER PROMPT ---');
+            console.log(buildUserPrompt(img.exif, img.analysis));
+            console.log(`\n--- IMAGE: ${img.filename} (${opts.useThumbnails ? 'thumbnail' : 'full-res'}) ---`);
+            const imgPath = opts.useThumbnails
+                ? path.join(PATHS.thumbnailDir, img.thumbnail.replace('thumbnails/', ''))
+                : path.join(PATHS.webpDir, img.path.replace('webp/', ''));
+            console.log(`Path: ${imgPath}`);
+        }
+        return;
+    }
+    // Process with concurrency control
+    let active = 0;
+    let idx = 0;
+    async function processOne(img) {
+        const imgPath = opts.useThumbnails
+            ? path.join(PATHS.thumbnailDir, img.thumbnail.replace('thumbnails/', ''))
+            : path.join(PATHS.webpDir, img.path.replace('webp/', ''));
+        try {
+            const result = await analyzeImage(imgPath, img.filename, img.exif, img.analysis, opts.model);
+            progress.completed[result.filename] = result.analysis;
+            progress.totalCostUsd += result.costUsd;
+            progress.totalInputTokens += result.inputTokens;
+            progress.totalOutputTokens += result.outputTokens;
+            saveProgress(progress);
+            const tier = result.analysis.curatorial.tier;
+            const score = result.analysis.curatorial.score;
+            log(`${result.filename} | ${score} | ${tier} | $${progress.totalCostUsd.toFixed(2)}/$${opts.costLimit.toFixed(2)}`);
+        }
+        catch (err) {
+            const errMsg = err?.message || String(err);
+            log(`ERROR ${img.filename}: ${errMsg}`);
+            progress.errors.push({
+                filename: img.filename,
+                error: errMsg,
+                timestamp: new Date().toISOString(),
+            });
+            saveProgress(progress);
+            // Retry once on non-validation errors
+            if (!errMsg.includes('ZodError') && !errMsg.includes('parse')) {
+                log(`retrying ${img.filename}...`);
+                try {
+                    const result = await analyzeImage(imgPath, img.filename, img.exif, img.analysis, opts.model);
+                    progress.completed[result.filename] = result.analysis;
+                    progress.totalCostUsd += result.costUsd;
+                    progress.totalInputTokens += result.inputTokens;
+                    progress.totalOutputTokens += result.outputTokens;
+                    saveProgress(progress);
+                    log(`${result.filename} | ${result.analysis.curatorial.score} | ${result.analysis.curatorial.tier} | $${progress.totalCostUsd.toFixed(2)}/$${opts.costLimit.toFixed(2)} (retry)`);
+                }
+                catch (retryErr) {
+                    log(`RETRY FAILED ${img.filename}: ${retryErr?.message || retryErr}`);
+                }
+            }
+        }
+    }
+    // Simple concurrency pool
+    const queue = [...pending];
+    const sessionStartCost = progress.totalCostUsd;
+    async function worker() {
+        while (queue.length > 0) {
+            // Check cost limit (per-session spend, not cumulative)
+            const sessionCost = progress.totalCostUsd - sessionStartCost;
+            if (sessionCost >= opts.costLimit) {
+                log(`session cost limit reached: $${sessionCost.toFixed(2)} >= $${opts.costLimit.toFixed(2)} (cumulative: $${progress.totalCostUsd.toFixed(2)})`);
+                return;
+            }
+            const img = queue.shift();
+            await processOne(img);
+        }
+    }
+    const workers = Array.from({ length: Math.min(opts.concurrency, queue.length) }, () => worker());
+    await Promise.all(workers);
+    // Build HENRI manifest
+    const henriManifest = {
+        metadata: {
+            ...siteManifest.metadata,
+            henriVersion: '2.0',
+            henriAnalysisDate: new Date().toISOString(),
+        },
+        images: siteManifest.images.map(img => ({
+            ...img,
+            henriAnalysis: progress.completed[img.filename],
+        })),
+    };
+    saveHenriManifest(henriManifest);
+    const completedCount = Object.keys(progress.completed).length;
+    const errorCount = progress.errors.length;
+    log(`batch complete: ${completedCount} analyzed, ${errorCount} errors, $${progress.totalCostUsd.toFixed(2)} total`);
+    // Tier breakdown
+    const tiers = { discard: 0, study: 0, strong: 0, portfolio: 0, exhibition: 0 };
+    for (const analysis of Object.values(progress.completed)) {
+        tiers[analysis.curatorial.tier]++;
+    }
+    log(`tiers: ${Object.entries(tiers).map(([k, v]) => `${k}=${v}`).join(', ')}`);
+}

package/dist/analyze/local-analyzer.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Local Analyzer — TypeScript orchestrator for Python compute modules.
+ *
+ * Calls Python workers via child_process (same pattern as osxphotos integration).
+ * Manages checkpointing and result merging.
+ */
+export declare function runEmbeddings(manifestPath?: string): void;
+export declare function runColors(manifestPath?: string): void;
+export declare function runFaces(manifestPath?: string): void;
+export declare function runGeometry(manifestPath?: string): void;
+export declare function runOcr(manifestPath?: string): void;
+export declare function runTemporal(manifestPath?: string): void;
+export declare function runScene(manifestPath?: string): void;
+export declare function runClustering(): void;
+export declare function runFullPipeline(manifestPath?: string): void;
+export declare function computeStatus(): void;

package/dist/analyze/local-analyzer.js

@@ -0,0 +1,119 @@
+/**
+ * Local Analyzer — TypeScript orchestrator for Python compute modules.
+ *
+ * Calls Python workers via child_process (same pattern as osxphotos integration).
+ * Manages checkpointing and result merging.
+ */
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { PATHS } from '../lib/config.js';
+import { log } from '../lib/state.js';
+function ensureOutputDir() {
+    fs.mkdirSync(PATHS.embeddingsDir, { recursive: true });
+}
+function runPython(command, args, timeoutMs = 600_000) {
+    const pythonCmd = `python3 -m compute ${command} ${args.join(' ')}`;
+    log(`running: ${pythonCmd}`);
+    try {
+        const output = execSync(pythonCmd, {
+            cwd: path.join(PATHS.computeDir, '..'), // Run from src/ so `compute` is a package
+            timeout: timeoutMs,
+            maxBuffer: 50 * 1024 * 1024,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return output;
+    }
+    catch (err) {
+        const stderr = err.stderr?.toString() || '';
+        const stdout = err.stdout?.toString() || '';
+        log(`compute error: ${stderr.substring(0, 500)}`);
+        if (stdout)
+            log(`compute stdout: ${stdout.substring(0, 500)}`);
+        throw err;
+    }
+}
+// ─── Individual Module Runners ──────────────────────────────────────
+export function runEmbeddings(manifestPath) {
+    const manifest = manifestPath || PATHS.henriManifest;
+    ensureOutputDir();
+    const output = runPython('embed', ['--manifest', manifest, '--output', PATHS.embeddingsDir]);
+    log(output.trim().split('\n').pop() || 'embeddings done');
+}
+export function runColors(manifestPath) {
+    const manifest = manifestPath || PATHS.henriManifest;
+    ensureOutputDir();
+    const output = runPython('colors', ['--manifest', manifest, '--output', path.join(PATHS.embeddingsDir, 'colors.json')]);
+    log(output.trim().split('\n').pop() || 'colors done');
+}
+export function runFaces(manifestPath) {
+    const manifest = manifestPath || PATHS.henriManifest;
+    ensureOutputDir();
+    const output = runPython('faces', ['--manifest', manifest, '--output', path.join(PATHS.embeddingsDir, 'faces.json')]);
+    log(output.trim().split('\n').pop() || 'faces done');
+}
+export function runGeometry(manifestPath) {
+    const manifest = manifestPath || PATHS.henriManifest;
+    ensureOutputDir();
+    const output = runPython('geometry', ['--manifest', manifest, '--output', path.join(PATHS.embeddingsDir, 'geometry.json')]);
+    log(output.trim().split('\n').pop() || 'geometry done');
+}
+export function runOcr(manifestPath) {
+    const manifest = manifestPath || PATHS.henriManifest;
+    ensureOutputDir();
+    const output = runPython('ocr', ['--manifest', manifest, '--output', path.join(PATHS.embeddingsDir, 'ocr.json')]);
+    log(output.trim().split('\n').pop() || 'ocr done');
+}
+export function runTemporal(manifestPath) {
+    const manifest = manifestPath || PATHS.henriManifest;
+    ensureOutputDir();
+    const output = runPython('temporal', ['--manifest', manifest, '--output', path.join(PATHS.embeddingsDir, 'temporal.json')]);
+    log(output.trim().split('\n').pop() || 'temporal done');
+}
+export function runScene(manifestPath) {
+    const manifest = manifestPath || PATHS.henriManifest;
+    ensureOutputDir();
+    const output = runPython('scene', ['--manifest', manifest, '--output', path.join(PATHS.embeddingsDir, 'scenes.json')]);
+    log(output.trim().split('\n').pop() || 'scene done');
+}
+export function runClustering() {
+    ensureOutputDir();
+    const output = runPython('cluster', ['--embeddings-dir', PATHS.embeddingsDir, '--output', path.join(PATHS.embeddingsDir, 'clusters.json')]);
+    log(output.trim().split('\n').pop() || 'clustering done');
+}
+// ─── Full Pipeline ──────────────────────────────────────────────────
+export function runFullPipeline(manifestPath) {
+    const manifest = manifestPath || PATHS.henriManifest;
+    ensureOutputDir();
+    const output = runPython('analyze-all', ['--manifest', manifest, '--output-dir', PATHS.embeddingsDir], 1_200_000);
+    log(output.trim().split('\n').pop() || 'full pipeline done');
+}
+// ─── Status ─────────────────────────────────────────────────────────
+export function computeStatus() {
+    const modules = [
+        { name: 'CLIP embeddings', file: 'clip-embeddings.npy' },
+        { name: 'CLIP index', file: 'clip-index.json' },
+        { name: 'Colors', file: 'colors.json' },
+        { name: 'Faces', file: 'faces.json' },
+        { name: 'Face embeddings', file: 'face-embeddings.npy' },
+        { name: 'Geometry', file: 'geometry.json' },
+        { name: 'OCR', file: 'ocr.json' },
+        { name: 'Temporal', file: 'temporal.json' },
+        { name: 'Scenes', file: 'scenes.json' },
+        { name: 'Clusters', file: 'clusters.json' },
+    ];
+    log(`compute output dir: ${PATHS.embeddingsDir}`);
+    for (const mod of modules) {
+        const filePath = path.join(PATHS.embeddingsDir, mod.file);
+        if (fs.existsSync(filePath)) {
+            const stat = fs.statSync(filePath);
+            const sizeKb = Math.round(stat.size / 1024);
+            const modified = stat.mtime.toISOString().substring(0, 19);
+            log(`  ${mod.name}: ${sizeKb}KB (${modified})`);
+        }
+        else {
+            log(`  ${mod.name}: not computed`);
+        }
+    }
+}