@quietloudlab/ai-interaction-atlas 1.0.1 → 1.0.2

package/README.md

@@ -4,24 +4,78 @@
 [![License](https://img.shields.io/npm/l/@quietloudlab/ai-interaction-atlas)](https://opensource.org/licenses/Apache-2.0)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)
 
-A shared language for designing AI experiences across human actions, AI tasks, system operations, data, constraints, and touchpoints.
+A shared language for designing **legible, inspectable AI systems**.
 
-**100+ interaction patterns** organized into **6 system dimensions** to help you design inspectable, responsible AI systems.
+The AI Interaction Atlas is a structured taxonomy of interaction patterns used to design, reason about, and document human–AI systems. It focuses on *how systems behave*, *where agency lives*, and *what constraints shape outcomes* — not just models or UI.
 
-🌐 [**Explore the Atlas**](https://ai-interaction.com) | 📖 [**Documentation**](https://ai-interaction.com/rationale) | 🐙 [**GitHub**](https://github.com/quietloudlab/ai-interaction-atlas)
+**180 structured elements** across **6 system dimensions**, designed to make AI systems visible before they are built.
+
+🌐 **Explore the Atlas:** https://ai-interaction.com  
+🐙 **GitHub:** https://github.com/quietloudlab/ai-interaction-atlas  
 
 ---
 
-## Why Use This Package?
+## What This Package Is
+
+This npm package provides the **Atlas data and utilities**:
 
-The AI Interaction Atlas provides structured data for:
+- A curated, opinionated dataset of AI interaction patterns
+- Strongly typed structures for tasks, data, constraints, and touchpoints
+- Search, filtering, and validation utilities
+- Zero dependencies, tree-shakeable, framework-agnostic
 
-- 🤖 **Building AI coding assistants** that understand interaction design patterns
-- 🛠️ **Creating design tools** that reference the taxonomy
-- 📊 **Validating AI workflows** against established patterns
-- 🔍 **Searching patterns programmatically** by keyword or dimension
-- 📝 **Generating documentation** from interaction flows
-- 🧪 **Training and education** with structured AI design patterns
+It is designed to be used:
+- in code
+- in prompts
+- in documentation
+- in tools built by you or the community
+
+---
+
+## What This Package Is *Not*
+
+- ❌ Not an AI framework
+- ❌ Not a UI kit
+- ❌ Not an orchestration engine
+- ❌ Not a visual editor
+
+> **Note:**  
+> A visual canvas for composing and mapping systems using the Atlas is being explored separately.  
+> This package intentionally focuses on the **language layer**, not the tooling.
+
+---
+
+## Who This Is For
+
+You may find the Atlas useful if you are:
+
+- Designing AI-powered products or workflows
+- Building internal tools or design systems for AI teams
+- Creating AI assistants that reason about interaction patterns
+- Documenting or auditing AI systems
+- Teaching or learning applied AI system design
+
+You do **not** need to be an ML engineer to use the Atlas.  
+It encodes *design intent and system behavior*, not implementation details.
+
+---
+
+## Why Use the Atlas?
+
+Most AI products are designed at the wrong level of abstraction.
+
+Teams jump to:
+> “Use an LLM”  
+> “Add an agent”  
+> “Automate this”
+
+Instead of asking:
+- Where does human judgment remain essential?
+- Which decisions are probabilistic vs deterministic?
+- What constraints govern safety, latency, or trust?
+- Who is accountable when the system fails?
+
+The Atlas provides a **shared vocabulary** to answer those questions *before* systems harden.
 
 ---
 
@@ -43,46 +97,54 @@ pnpm add @quietloudlab/ai-interaction-atlas
 
 ## Quick Start
 
-```typescript
+```ts
 import {
   AI_TASKS,
-  HUMAN_TASKS,
-  SYSTEM_TASKS,
   searchPatterns,
   getPattern,
+  validateWorkflow,
   getAtlasStats
 } from '@quietloudlab/ai-interaction-atlas';
 
-// Get all AI capabilities
+// Inspect available AI capabilities
 console.log(`${AI_TASKS.length} AI task patterns available`);
 
-// Search for patterns
+// Search patterns by keyword
 const reviewPatterns = searchPatterns('review', { dimensions: ['human'] });
-console.log(reviewPatterns);
 
-// Get a specific pattern by ID
-const classifyTask = getPattern('classify-intent');
-console.log(classifyTask?.description);
+// Retrieve a specific pattern
+const classifyIntent = getPattern('classify-intent');
+console.log(classifyIntent?.description);
+
+// Validate a proposed system workflow
+const validation = validateWorkflow([
+  'ai_classify_intent',
+  'human_review_output',
+  'system_log_event'
+]);
+
+if (!validation.valid) {
+  console.error('Invalid pattern IDs:', validation.invalidIds);
+}
 
 // Get Atlas statistics
-const stats = getAtlasStats();
-console.log(`Total patterns: ${stats.total}`);
+console.log(getAtlasStats());
 ```
 
 ---
 
-## The Six Dimensions
+## The Six System Dimensions
 
-The Atlas organizes AI interactions into six core dimensions:
+The Atlas models AI systems as compositions of six dimensions:
 
-| Dimension | Description | Count |
-|-----------|-------------|-------|
-| **AI Tasks** | Probabilistic capabilities (detect, classify, generate, transform) | 45+ |
-| **Human Tasks** | Human actions in the loop (review, approve, configure, decide) | 28+ |
-| **System Tasks** | Infrastructure operations (routing, caching, logging, state) | 31+ |
-| **Data Artifacts** | Information types that flow through the system | 52+ |
-| **Constraints** | Boundaries that shape design (latency, privacy, cost, quality) | 42+ |
-| **Touchpoints** | Where interactions happen (UI, API, voice, AR) | 18+ |
+| Dimension | Description |
+|---------|-------------|
+| **AI Patterns** | Probabilistic capabilities (detect, classify, generate, transform) |
+| **Human Actions** | Where human agency lives (review, approve, decide, configure) |
+| **System Operations** | Deterministic infrastructure behavior (routing, caching, logging) |
+| **Data Artifacts** | Inputs, outputs, and contextual information |
+| **Constraints** | Boundaries that shape behavior (latency, privacy, accuracy, cost) |
+| **Touchpoints** | Where systems surface (UI, API, voice, notifications) |
 
 ---
 
@@ -90,24 +152,24 @@ The Atlas organizes AI interactions into six core dimensions:
 
 ### Data Collections
 
-```typescript
+```ts
 import {
-  AI_TASKS,           // Array of AI capability patterns
-  HUMAN_TASKS,        // Array of human action patterns
-  SYSTEM_TASKS,       // Array of system operation patterns
-  DATA_ARTIFACTS,     // Array of data type definitions
-  CONSTRAINTS,        // Array of constraint definitions
-  TOUCHPOINTS,        // Array of touchpoint definitions
-  LAYERS,             // Array of processing layer definitions
-  WORKFLOW_TEMPLATES, // Array of pre-built workflow templates
-  EXAMPLES,           // Array of real-world examples
-  ATLAS_DATA          // All data in one object
+  AI_TASKS,
+  HUMAN_TASKS,
+  SYSTEM_TASKS,
+  DATA_ARTIFACTS,
+  CONSTRAINTS,
+  TOUCHPOINTS,
+  LAYERS,
+  WORKFLOW_TEMPLATES,
+  EXAMPLES,
+  ATLAS_DATA
 } from '@quietloudlab/ai-interaction-atlas';
 ```
 
 ### Types
 
-```typescript
+```ts
 import type {
   AiTask,
   HumanTask,
@@ -123,371 +185,100 @@ import type {
 
 ---
 
-## API Reference
-
-### Search Functions
-
-#### `searchPatterns(query, options?)`
-
-Search across all Atlas patterns by keyword.
-
-```typescript
-import { searchPatterns } from '@quietloudlab/ai-interaction-atlas';
-
-// Search all dimensions
-const results = searchPatterns('review');
-
-// Search specific dimensions
-const humanResults = searchPatterns('review', {
-  dimensions: ['human']
-});
-
-// Case-sensitive search
-const exactMatches = searchPatterns('API', {
-  caseSensitive: true
-});
-
-// Limit results
-const topResults = searchPatterns('generate', {
-  dimensions: ['ai'],
-  limit: 5
-});
-```
-
-**Options:**
-- `dimensions?: Array<'ai' | 'human' | 'system' | 'data' | 'constraints' | 'touchpoints'>` - Dimensions to search (default: all)
-- `caseSensitive?: boolean` - Case sensitive search (default: false)
-- `searchDescription?: boolean` - Search in description field (default: true)
-- `limit?: number` - Limit number of results (default: no limit)
-
----
-
-#### `getPattern(id)`
-
-Get a specific pattern by ID (slug or target_id).
-
-```typescript
-import { getPattern } from '@quietloudlab/ai-interaction-atlas';
-
-const task = getPattern('classify-intent');
-const artifact = getPattern('embedding');
-const constraint = getPattern('privacy-compliance');
-
-if (task) {
-  console.log(task.name);
-  console.log(task.description);
-  console.log(task.inputs);
-  console.log(task.outputs);
-}
-```
-
----
-
-#### `getPatternsByDimension(dimension)`
-
-Get all patterns from a specific dimension.
-
-```typescript
-import { getPatternsByDimension } from '@quietloudlab/ai-interaction-atlas';
-
-const aiTasks = getPatternsByDimension('ai');
-const constraints = getPatternsByDimension('constraints');
-```
-
----
-
-### Filter Functions
-
-#### `filterByLayer(tasks, layerId)`
-
-Filter tasks by processing layer.
+## API Overview
 
-```typescript
-import { AI_TASKS, filterByLayer } from '@quietloudlab/ai-interaction-atlas';
+### `searchPatterns(query, options?)`
+Search across all Atlas elements by keyword.
 
-const inboundTasks = filterByLayer(AI_TASKS, 'layer_inbound');
-const internalTasks = filterByLayer(AI_TASKS, 'layer_internal');
+```ts
+searchPatterns('review', { dimensions: ['human'], limit: 5 });
 ```
 
----
-
-#### `getTasksByLayer(layerId)`
-
-Get all tasks (AI, Human, System) in a specific layer.
+### `getPattern(id)`
+Retrieve a single pattern by ID (slug or target_id).
 
-```typescript
-import { getTasksByLayer } from '@quietloudlab/ai-interaction-atlas';
-
-const inbound = getTasksByLayer('layer_inbound');
-console.log(inbound.ai);     // AI tasks in inbound layer
-console.log(inbound.human);  // Human tasks in inbound layer
-console.log(inbound.system); // System tasks in inbound layer
+```ts
+getPattern('privacy-compliance');
 ```
 
----
-
-#### `filterArtifactsByCategory(category)`
-
-Filter data artifacts by category.
-
-```typescript
-import { filterArtifactsByCategory } from '@quietloudlab/ai-interaction-atlas';
+### `getPatternsByDimension(dimension)`
+Retrieve all patterns from one dimension.
 
-const textArtifacts = filterArtifactsByCategory('text');
-const visualArtifacts = filterArtifactsByCategory('visual');
+```ts
+getPatternsByDimension('constraints');
 ```
 
----
-
-#### `getAtlasStats()`
-
-Get statistics about the Atlas.
-
-```typescript
-import { getAtlasStats } from '@quietloudlab/ai-interaction-atlas';
-
-const stats = getAtlasStats();
-console.log(stats);
-// {
-//   ai: 45,
-//   human: 28,
-//   system: 31,
-//   data: 52,
-//   constraints: 42,
-//   touchpoints: 18,
-//   layers: 4,
-//   total: 216
-// }
-```
-
----
+### `validateWorkflow(nodeIds)`
+Validate that a workflow uses valid Atlas elements.
 
-### Validation Functions
-
-#### `isValidTaskId(taskId)`
-
-Check if a task ID exists in the Atlas.
-
-```typescript
-import { isValidTaskId } from '@quietloudlab/ai-interaction-atlas';
-
-if (isValidTaskId('ai_classify_intent')) {
-  console.log('Valid task!');
-}
-```
-
----
-
-#### `validateWorkflow(nodeIds)`
-
-Validate a workflow design.
-
-```typescript
-import { validateWorkflow } from '@quietloudlab/ai-interaction-atlas';
-
-const result = validateWorkflow([
-  'ai_classify_intent',
+```ts
+validateWorkflow([
+  'ai_generate_text',
   'human_review_output',
-  'system_log_event'
+  'system_store_result'
 ]);
-
-if (!result.valid) {
-  console.error('Invalid IDs:', result.invalidIds);
-}
-```
-
----
-
-#### Type Guards
-
-```typescript
-import { isAiTask, isHumanTask, isSystemTask } from '@quietloudlab/ai-interaction-atlas';
-
-if (isAiTask(someTask)) {
-  // TypeScript knows this is an AiTask
-  console.log(someTask.layer);
-}
-```
-
----
-
-## Real-World Use Cases
-
-### 1. LLM System Prompt
-
-Include Atlas patterns in your AI assistant's context:
-
-```typescript
-import { AI_TASKS, HUMAN_TASKS } from '@quietloudlab/ai-interaction-atlas';
-
-const systemPrompt = `
-You are an AI workflow designer. Use these interaction patterns from the AI Interaction Atlas:
-
-AI Capabilities:
-${AI_TASKS.map(t => `- ${t.name}: ${t.description}`).join('\n')}
-
-Human Actions:
-${HUMAN_TASKS.map(t => `- ${t.name}: ${t.description}`).join('\n')}
-
-Design workflows that combine these patterns effectively.
-`;
 ```
 
 ---
 
-### 2. Validate Workflow Designs
-
-Ensure workflows use valid patterns:
-
-```typescript
-import { validateWorkflow, getPattern } from '@quietloudlab/ai-interaction-atlas';
-
-function analyzeWorkflow(nodeIds: string[]) {
-  const validation = validateWorkflow(nodeIds);
+## Real-World Uses
 
-  if (!validation.valid) {
-    console.error('Invalid patterns:', validation.invalidIds);
-    return false;
-  }
-
-  // Analyze each node
-  nodeIds.forEach(id => {
-    const pattern = getPattern(id);
-    console.log(`✓ ${pattern?.name}`);
-  });
-
-  return true;
-}
-```
-
----
-
-### 3. Generate Documentation
-
-Auto-generate workflow documentation:
-
-```typescript
-import { getPattern } from '@quietloudlab/ai-interaction-atlas';
-
-function documentWorkflow(nodeIds: string[]) {
-  const docs = nodeIds.map(id => {
-    const pattern = getPattern(id);
-    if (!pattern) return null;
-
-    return {
-      name: pattern.name,
-      description: pattern.description,
-      inputs: pattern.inputs,
-      outputs: pattern.outputs
-    };
-  }).filter(Boolean);
-
-  return docs;
-}
-```
-
----
-
-### 4. Build a Pattern Search Tool
-
-Create a CLI tool for exploring patterns:
-
-```typescript
-import { searchPatterns, getAtlasStats } from '@quietloudlab/ai-interaction-atlas';
-
-function searchCLI(query: string) {
-  console.log('Searching Atlas...\n');
-
-  const results = searchPatterns(query);
-
-  console.log(`Found ${results.length} patterns:\n`);
-
-  results.forEach(pattern => {
-    console.log(`- ${pattern.name}`);
-    console.log(`  ${pattern.description}\n`);
-  });
-
-  const stats = getAtlasStats();
-  console.log(`\nAtlas contains ${stats.total} total patterns.`);
-}
-```
-
----
-
-### 5. Filter by Constraint
-
-Find patterns compatible with specific constraints:
-
-```typescript
-import {
-  AI_TASKS,
-  CONSTRAINTS,
-  filterConstraintsByCategory
-} from '@quietloudlab/ai-interaction-atlas';
-
-// Get all privacy-related constraints
-const privacyConstraints = filterConstraintsByCategory('Quality & Safety');
-
-// Find AI tasks suitable for high-privacy scenarios
-const privateTasks = AI_TASKS.filter(task => {
-  // Your custom logic to check compatibility
-  return task.description.toLowerCase().includes('privacy');
-});
-```
+- **Design audits:** Map an existing AI product to surface risks and gaps
+- **System prompts:** Ground AI assistants in real interaction patterns
+- **Documentation:** Generate inspectable system diagrams and specs
+- **Tooling:** Build search, validation, or mapping tools on top of the Atlas
+- **Education:** Teach applied AI system design with concrete language
 
 ---
 
 ## TypeScript Support
 
-This package is written in TypeScript and includes full type definitions.
-
-```typescript
-import type {
-  AiTask,
-  HumanTask,
-  IOSpec,
-  AtlasData
-} from '@quietloudlab/ai-interaction-atlas';
+Written in TypeScript with full type definitions.
 
+```ts
 function analyzeTask(task: AiTask) {
-  // Full type safety and autocomplete
-  const inputs: IOSpec | undefined = task.inputs;
-  const outputs: IOSpec | undefined = task.outputs;
-  const layer: string = task.layer;
+  console.log(task.layer);
+  console.log(task.inputs);
+  console.log(task.outputs);
 }
 ```
 
 ---
 
-## Bundle Size
+## Bundle & Dependencies
 
-- **~220KB** uncompressed
-- **Tree-shakeable** - import only what you need
-- **Zero dependencies** - pure data
+- ~220KB uncompressed
+- Tree-shakeable
+- Zero runtime dependencies
+- Pure data + utilities
 
 ---
 
 ## License
 
-Apache 2.0 - see [LICENSE](LICENSE) file for details.
+Apache 2.0 — free to use, modify, and integrate commercially.  
+See [LICENSE](LICENSE) for details.
 
 ---
 
 ## About
 
-Created by [Brandon Harwood](https://www.linkedin.com/in/brandon-harwood/) at [quietloudlab](https://quietloudlab.com), a design and research studio specializing in human-centered AI.
+Created by **Brandon Harwood** at **quietloudlab** —  
+a design and research studio focused on human-centered AI, system legibility, and responsible interaction design.
 
----
-
-## Links
-
-- 🌐 [Live Atlas](https://ai-interaction.com)
-- 📖 [Rationale](https://ai-interaction.com/rationale)
-- 🐙 [GitHub Repository](https://github.com/quietloudlab/ai-interaction-atlas)
-- 🐛 [Report Issues](https://github.com/quietloudlab/ai-interaction-atlas/issues)
+- 🌐 https://quietloudlab.com
+- 🌐 https://ai-interaction.com
 
 ---
 
 ## Contributing
 
-The Atlas is open source and contributions are welcome! See the main repository for contribution guidelines.
+The Atlas is open source and evolving.
+
+Contributions, issues, and discussions are welcome — especially around:
+- new patterns
+- clearer definitions
+- real-world examples
+- missing constraints
+
+See the GitHub repository for contribution guidelines.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quietloudlab/ai-interaction-atlas",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "A shared language for designing AI experiences - 100+ interaction patterns across human actions, AI tasks, system operations, data, constraints, and touchpoints",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -51,7 +51,7 @@
   "homepage": "https://ai-interaction.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/quietloudlab/ai-interaction-atlas.git",
+    "url": "git+https://github.com/quietloudlab/ai-interaction-atlas.git",
     "directory": "atlas-package"
   },
   "bugs": {