holosphere 1.0.8 → 1.1.0

package/README.md

@@ -1,176 +1,331 @@
 # HoloSphere
 
-HoloSphere is a decentralized geospatial data management system that combines hierarchical hexagonal tiling (H3) with distributed data storage (GunDB) and AI-powered processing of information.
+HoloSphere is a JavaScript library that provides a spatial data management system using H3 geospatial indexing and GunDB for distributed storage. It enables you to store, validate, and retrieve data organized by geographic location using holonic principles.
 
-## Installation
-
-```bash
-npm install holosphere
-```
+## What is a Holon?
 
-## Basic Usage
+A holon (from Greek 'holos' meaning whole, with suffix 'on' meaning part) is simultaneously a whole and a part. In HoloSphere, holons are implemented as hierarchical geographic cells that can:
 
-```javascript
-import HoloSphere from 'holosphere';
+1. Act as autonomous units (storing their own data)
+2. Be part of larger holons (through H3's hierarchical structure)
+3. Contain smaller holons (through subdivision)
+4. Interact with peer holons (through the distributed network)
 
-// Initialize HoloSphere
-const holo = new HoloSphere('my-app');
+### Holonic Architecture
 
-// Optional: Initialize with OpenAI
-const holoAI = new HoloSphere('my-app', 'your-openai-key');
-```
+HoloSphere implements holonic architecture in two ways:
 
-## Core Features
+#### 1. Spatial Hierarchy
+```javascript
+// Get holons at different scales for a location
+const holon = await sphere.getHolon(lat, lng, 7);  // City level
+const parent = h3.cellToParent(holon, 6);          // Region level
+const children = h3.cellToChildren(holon, 8);       // Neighborhood level
 
-### User Management
+// Get entire hierarchy
+const scales = sphere.getHolonScalespace(holon);    // All containing holons
+```
 
+#### 2. Data Organization
 ```javascript
-// Create a new user
-await holo.createUser('username', 'password');
-
-// Login
-await holo.login('username', 'password');
+// Store data in different aspects (lenses) of a holon
+await sphere.put(holon, 'environment', {
+    id: 'air-001',
+    temperature: 22.5,
+    humidity: 65
+});
 
-// Logout
-await holo.logout();
+await sphere.put(holon, 'social', {
+    id: 'event-001',
+    type: 'gathering',
+    participants: 50
+});
 ```
 
-### Schema Operations
+### Use Cases
+
+1. **Localized Structures**
+   - Local environmental monitoring
+   - Community event coordination
+   - Neighborhood resource sharing
+   - Municipal service management
 
 ```javascript
-// Define a schema for a lens
-const schema = {
-    type: 'object',
-    properties: {
-        id: { type: 'string' },
-        data: { type: 'string' }
-    },
-    required: ['id', 'data']
-};
+// Example: Local air quality monitoring
+async function monitorLocalAir(lat, lng) {
+    const neighborhood = await sphere.getHolon(lat, lng, 9);
+    
+    // Store reading
+    await sphere.put(neighborhood, 'air-quality', {
+        id: `reading-${Date.now()}`,
+        pm25: 12.5,
+        timestamp: Date.now()
+    });
+    
+    // Get local trends
+    const readings = await sphere.getAll(neighborhood, 'air-quality');
+}
+```
 
-// Set schema for a lens
-await holo.setLensSchema('myLens', schema);
+2. **Delocalized Structures**
+   - Regional data aggregation
+   - Cross-boundary collaboration
+   - Distributed decision making
+   - Resource flow tracking
 
-// Get schema for a lens
-const lensSchema = await holo.getLensSchema('myLens');
+```javascript
+// Example: Regional resource coordination
+async function coordinateResources(region) {
+    // Get all sub-holons
+    const localities = h3.cellToChildren(region, h3.getResolution(region) + 1);
+    
+    // Gather resource data from each locality
+    const resources = await Promise.all(
+        localities.map(async locality => {
+            return sphere.getAll(locality, 'resources');
+        })
+    );
+    
+    // Compute summaries for parent holon
+    await sphere.compute(region, 'resources', 'summarize');
+}
 ```
 
-### Global Data Operations
+3. **Hybrid Structures**
+   - Adaptive governance systems
+   - Scalable social networks
+   - Emergency response coordination
+   - Supply chain management
 
 ```javascript
-// Store data globally
-await holo.putGlobalData('settings', {
-    id: 'config1',
-    theme: 'dark'
-});
+// Example: Emergency response system
+async function coordinateEmergency(incident) {
+    const epicenter = await sphere.getHolon(incident.lat, incident.lng, 8);
+    const region = h3.cellToParent(epicenter, 6);
+    
+    // Local response
+    await sphere.put(epicenter, 'emergencies', {
+        id: incident.id,
+        type: incident.type,
+        severity: incident.severity
+    });
+    
+    // Regional coordination
+    const nearbyResources = await sphere.getAll(region, 'resources');
+    
+    // Subscribe to updates
+    sphere.subscribe(epicenter, 'emergencies', (data) => {
+        updateResponsePlan(data);
+    });
+}
+```
 
-// Get all data from a table
-const allSettings = await holo.getGlobalData('settings');
+### Key Benefits
 
-// Get specific data by key
-const config = await holo.getGlobalDataKey('settings', 'config1');
+1. **Scalability**: Holons can be nested infinitely, allowing systems to scale organically
+2. **Autonomy**: Each holon manages its own data while participating in larger structures
+3. **Flexibility**: Systems can be organized both hierarchically and peer-to-peer
+4. **Resilience**: Distributed storage ensures no single point of failure
+5. **Adaptability**: Structures can evolve based on changing needs
 
-// Delete a global table
-await holo.deleteGlobalData('settings');
+## Installation
+
+```bash
+npm install holosphere
 ```
 
-### Hex Data Operations
+## Quick Start
 
 ```javascript
-// Store data in a hex
-await holo.putHexData('hex123', 'observations', {
-    id: 'obs1',
-    data: 'value'
-});
-
-// Get all data from a hex/lens
-const data = await holo.getHexData('hex123', 'observations');
+import HoloSphere from 'holosphere';
 
-// Get specific data by key
-const item = await holo.getHexKey('hex123', 'observations', 'obs1');
+// Initialize HoloSphere
+const sphere = new HoloSphere('my-app');
+
+// Store data at a location
+const holon = await sphere.getHolon(40.7128, -74.0060, 7); // NYC at resolution 7
+await sphere.put(holon, 'observations', {
+    id: 'obs-001',
+    temperature: 22.5,
+    timestamp: Date.now()
+});
+```
 
-// Get raw GunDB node
-const node = await holo.getHexNode('hex123', 'observations', 'obs1');
+## Real-World Examples
 
-// Delete specific data
-await holo.deleteHexData('hex123', 'observations', 'obs1');
+### Environmental Monitoring System
 
-// Delete a node by tag
-await holo.deleteNode('nodeId', 'tag');
+```javascript
+// Define a schema for temperature readings
+const tempSchema = {
+    type: 'object',
+    properties: {
+        id: { type: 'string' },
+        temperature: { type: 'number' },
+        humidity: { type: 'number' },
+        timestamp: { type: 'number' }
+    },
+    required: ['id', 'temperature', 'timestamp']
+};
 
-// Clear all data in a lens
-await holo.clearlens('hex123', 'observations');
+// Set up the system
+const sphere = new HoloSphere('env-monitor', true); // strict mode enabled
+await sphere.setSchema('temperature', tempSchema);
+
+// Store a reading
+async function storeReading(lat, lng, temp, humidity) {
+    const holon = await sphere.getHolon(lat, lng, 8);
+    const reading = {
+        id: `temp-${Date.now()}`,
+        temperature: temp,
+        humidity: humidity,
+        timestamp: Date.now()
+    };
+    
+    return sphere.put(holon, 'temperature', reading);
+}
+
+// Get all readings for an area
+async function getAreaReadings(lat, lng) {
+    const holon = await sphere.getHolon(lat, lng, 8);
+    return sphere.getAll(holon, 'temperature');
+}
+
+// Monitor an area for new readings
+function monitorArea(lat, lng, callback) {
+    const holon = sphere.getHolon(lat, lng, 8);
+    sphere.subscribe(holon, 'temperature', callback);
+}
 ```
 
-### Encrypted Data
+### Location-Based Content System
 
 ```javascript
-// Store encrypted data (requires authenticated user)
-await holo.putHexData('hex123', 'private', {
-    id: 'secret1',
-    data: 'sensitive'
-}, true, 'encryption-key');
+// Initialize with AI capabilities for content summarization
+const sphere = new HoloSphere('local-content', false, 'your-openai-key');
 
-// Encrypt specific data
-const encrypted = await holo.encrypt(data, 'secret-key');
+// Define content schema
+const contentSchema = {
+    type: 'object',
+    properties: {
+        id: { type: 'string' },
+        title: { type: 'string' },
+        content: { type: 'string' },
+        author: { type: 'string' },
+        timestamp: { type: 'number' }
+    },
+    required: ['id', 'title', 'content', 'author']
+};
 
-// Decrypt data
-const decrypted = await holo.decrypt(encrypted, 'secret-key');
+await sphere.setSchema('articles', contentSchema);
+
+// Post content for a location
+async function postLocalContent(lat, lng, title, content, author) {
+    const holon = await sphere.getHolon(lat, lng, 7);
+    const article = {
+        id: `article-${Date.now()}`,
+        title,
+        content,
+        author,
+        timestamp: Date.now()
+    };
+    
+    await sphere.put(holon, 'articles', article);
+    
+    // Generate summaries for parent areas
+    await sphere.compute(holon, 'articles', 'summarize');
+}
+
+// Get content for multiple zoom levels
+async function getAreaContent(lat, lng) {
+    const holon = await sphere.getHolon(lat, lng, 7);
+    const scales = sphere.getHolonScalespace(holon);
+    
+    const content = {};
+    for (const scale of scales) {
+        content[scale] = await sphere.getAll(scale, 'articles');
+    }
+    
+    return content;
+}
 ```
 
-### Geospatial Operations
+### Data Validation Example
 
 ```javascript
-// Get hex from coordinates
-const hex = await holo.getHex(37.7749, -74.0060, 7);
+// Strict validation with custom schema
+const sphere = new HoloSphere('validated-data', true);
 
-// Get all scales for coordinates
-const scales = holo.getScalespace(37.7749, -74.0060);
+const measurementSchema = {
+    type: 'object',
+    properties: {
+        id: { type: 'string' },
+        value: { type: 'number' },
+        unit: { type: 'string' },
+        accuracy: { type: 'number' },
+        timestamp: { type: 'number' }
+    },
+    required: ['id', 'value', 'unit'],
+    additionalProperties: false
+};
 
-// Get all parent hexes
-const parents = holo.getHexScalespace('hex123');
+await sphere.setSchema('measurements', measurementSchema);
 
-// Compute operations on hex data
-await holo.compute('hex123', 'observations', 'summarize');
+// This will succeed
+await sphere.put(holon, 'measurements', {
+    id: 'measure-1',
+    value: 42.5,
+    unit: 'celsius',
+    accuracy: 0.1,
+    timestamp: Date.now()
+});
 
-// Upcast data to parent hexes
-await holo.upcast('hex123', 'observations', data);
+// This will fail due to schema validation
+await sphere.put(holon, 'measurements', {
+    id: 'measure-2',
+    value: "invalid", // wrong type
+    extra: "field"    // not allowed
+});
 ```
 
-### Real-time Subscriptions
+## API Reference
 
+### Constructor
 ```javascript
-// Subscribe to changes
-holo.subscribe('hex123', 'observations', (data, key) => {
-    console.log('Updated data:', data);
-    console.log('Key:', key);
-});
+new HoloSphere(
+    appName,    // String: Namespace for your application
+    strict,     // Boolean: Enable strict schema validation (default: false)
+    openaikey   // String: Optional OpenAI API key for AI features
+)
 ```
 
-### Voting System
+### Core Methods
 
-```javascript
-// Get final vote (including delegations)
-const finalVote = holo.getFinalVote(userId, topic, votes);
+- `async getHolon(lat, lng, resolution)` - Get H3 index for coordinates
+- `async put(holon, lens, data)` - Store data
+- `async get(holon, lens, key)` - Retrieve specific data
+- `async getAll(holon, lens)` - Retrieve all data
+- `async delete(holon, lens, key)` - Delete specific data
+- `async deleteAll(holon, lens)` - Delete all data
+- `async setSchema(lens, schema)` - Set JSON schema for validation
+- `async getSchema(lens)` - Get current schema
+- `subscribe(holon, lens, callback)` - Listen for changes
 
-// Get aggregated votes for a hex
-const results = holo.aggregateVotes(hexId, topic);
+## Storage Architecture
 
-// Delegate voting power
-await holo.delegateVote(userId, topic, delegateId);
+Data in HoloSphere is organized by:
+- **Holons**: H3 geographic indexes
+- **Lenses**: Data categories/types
+- **Items**: Individual data entries with unique IDs
 
-// Cast a vote
-await holo.vote(userId, hexId, topic, voteChoice);
-```
+## Dependencies
+
+- h3-js: Uber's H3 geospatial indexing
+- gun: Decentralized database
+- ajv: JSON Schema validation
+- openai: AI capabilities (optional)
 
 ## License
 
 GPL-3.0-or-later
 
-## Dependencies
-
-- h3-js: Uber's H3 geospatial indexing system
-- gun: Decentralized graph database
-- ajv: JSON Schema validation
-- openai: OpenAI API client (optional)
-

package/holosphere.d.ts

@@ -1,34 +1,38 @@
 declare module 'holosphere' {
     export default class HoloSphere {
-        constructor(appName: string, openaikey?: string | null);
-
+        constructor(appName: string, strict?: boolean | null, openaikey?: string | null);
+        
         // User Management
         createUser(username: string, password: string): Promise<object>;
         login(username: string, password: string): Promise<object>;
         logout(): Promise<void>;
 
         // Schema Operations
-        setLensSchema(lens: string, schema: object): Promise<void>;
-        getLensSchema(lens: string): Promise<object | null>;
+        setSchema(lens: string, schema: object): Promise<void>;
+        getSchema(lens: string): Promise<object | null>;
 
         // Encryption Operations
         encrypt(data: any, secret: string): Promise<string>;
         decrypt(encryptedData: string, secret: string): Promise<any>;
 
-        // Global Data Operations
-        putGlobalData(tableName: string, data: object): Promise<void>;
-        getGlobalData(tableName: string): Promise<object | null>;
-        getGlobalDataKey(tableName: string, key: string): Promise<object | null>;
-        deleteGlobalData(tableName: string): Promise<void>;
-
         // Hex Data Operations
-        putHexData(hexId: string, lens: string, content: object, encrypt?: boolean, secret?: string | null): Promise<void>;
-        getHexData(hexId: string, lens: string, secret?: string | null): Promise<Array<any>>;
-        getHexKey(hexId: string, lens: string, key: string): Promise<any | null>;
-        getHexNode(hexId: string, lens: string, key: string): Promise<any>;
-        deleteHexData(hexId: string, lens: string, contentId: string): Promise<void>;
-        deleteNode(nodeId: string, tag: string): Promise<void>;
-        clearlens(hex: string, lens: string): Promise<void>;
+        put(holon: string, lens: string, content: object, encrypt?: boolean, secret?: string | null): Promise<void>;
+        get(holon: string, lens: string, key: string): Promise<any | null>;
+        delete(holon: string, lens: string, contentId: string): Promise<void>;
+        getAll(holon: string, lens: string, secret?: string | null): Promise<Array<any>>;
+        deleteAll(holon: string, lens: string): Promise<void>; 
+     
+        // Node Operations
+        putNode(holon: string, lens: string, node: object): Promise<void>;
+        getNode(holon: string, lens: string, key: string): Promise<any>;
+        deleteNode(holon: string, lens: string, key: string): Promise<void>;
+
+        // Global Data Operations
+        putGlobal(tableName: string, data: object): Promise<void>;
+        getGlobal(tableName: string, key: string): Promise<object | null>;
+        deleteGlobal(tableName: string, key: string): Promise<void>;
+        getAllGlobal(tableName: string): Promise<object | null>;
+        deleteAllGlobal(tableName: string): Promise<void>;
 
         // Geospatial Operations
         getHex(lat: number, lng: number, resolution: number): Promise<string>;
@@ -38,12 +42,7 @@ declare module 'holosphere' {
         upcast(hex: string, lens: string, content: any): Promise<any>;
 
         // Subscription
-        subscribe(hex: string, lens: string, callback: (data: any, key: string) => void): void;
-
-        // Voting System
-        getFinalVote(userId: string, topic: string, votes: object, visited?: Set<string>): string | null;
-        aggregateVotes(hexId: string, topic: string): object;
-        delegateVote(userId: string, topic: string, delegateTo: string): Promise<void>;
-        vote(userId: string, hexId: string, topic: string, vote: string): Promise<void>;
+        subscribe(holon: string, lens: string, callback: (data: any, key: string) => void): void;
+        subscribeGlobal(tableName: string, callback: (data: any, key: string) => void): void;
     }
 }