holosphere 1.0.7 → 1.1.0

package/README.md

@@ -1,206 +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.
 
-## Features
+## What is a Holon?
 
-- **Hierarchical Spatial Data**: Uses Uber's H3 spatial indexing system for efficient geospatial data organization
-- **Decentralized Storage**: Built on GunDB for peer-to-peer data storage and synchronization
-- **Schema Validation**: JSON Schema validation for data integrity
-- **AI Processing**: Extensible AI-powered content analysis and summarization across hexagonal regions
-- **Voting System**: Built-in delegation and voting mechanisms for collaborative decision-making
-- **Multi-scale Operations**: Automatic content propagation across different spatial resolutions
+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:
 
-## License
+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)
+
+### Holonic Architecture
 
-GNU Lesser General Public License v3.0 (LGPL-3.0)
+HoloSphere implements holonic architecture in two ways:
 
-This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
+#### 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
 
-This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+// Get entire hierarchy
+const scales = sphere.getHolonScalespace(holon);    // All containing holons
+```
+
+#### 2. Data Organization
+```javascript
+// Store data in different aspects (lenses) of a holon
+await sphere.put(holon, 'environment', {
+    id: 'air-001',
+    temperature: 22.5,
+    humidity: 65
+});
 
-You should have received a copy of the GNU Lesser General Public License along with this library; if not, see <https://www.gnu.org/licenses/>.
+await sphere.put(holon, 'social', {
+    id: 'event-001',
+    type: 'gathering',
+    participants: 50
+});
+```
 
-### Key Points of LGPL-3.0
+### Use Cases
 
-- You can use this library in proprietary applications
-- Any modifications to the library itself must be distributed under LGPL
-- Applications that use the library don't have to be LGPL
-- If you modify the library, you must make the source code available
-- You must provide a way for users to relink with a modified version of the library
+1. **Localized Structures**
+   - Local environmental monitoring
+   - Community event coordination
+   - Neighborhood resource sharing
+   - Municipal service management
 
-## Dependencies
+```javascript
+// 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');
+}
+```
 
-### Core Dependencies
-- **h3-js**: Uber's H3 geospatial indexing system
-- **gun**: Decentralized graph database
-- **ajv**: JSON Schema validation
-- **lodash**: Utility functions
+2. **Delocalized Structures**
+   - Regional data aggregation
+   - Cross-boundary collaboration
+   - Distributed decision making
+   - Resource flow tracking
 
-### Optional Dependencies
-- **langchain**: AI/LLM integration framework
-- **openai**: OpenAI API client (optional)
+```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');
+}
+```
+
+3. **Hybrid Structures**
+   - Adaptive governance systems
+   - Scalable social networks
+   - Emergency response coordination
+   - Supply chain management
+
+```javascript
+// 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);
+    });
+}
+```
+
+### Key Benefits
 
-## Getting Started
+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
+
+## Installation
 
 ```bash
 npm install holosphere
 ```
 
-## Basic Usage
+## Quick Start
 
 ```javascript
-import { HoloSphere } from 'holosphere';
+import HoloSphere from 'holosphere';
 
-// Initialize HoloSphere with your configuration
-const holo = new HoloSphere({
-  peers: ['http://localhost:8765/gun'],
-  aiProvider: 'local' // or 'openai', 'azure', etc.
-});
+// Initialize HoloSphere
+const sphere = new HoloSphere('my-app');
 
-// Create or access a hexagonal region
-const hex = await holo.getHex('8928308280fffff');
-
-// Store data in the region
-await hex.put({
-  type: 'observation',
-  data: {
+// 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()
-  }
-});
-
-// Subscribe to changes
-hex.subscribe(data => {
-  console.log('New data:', data);
 });
 ```
 
-## Advanced Features
+## Real-World Examples
 
-### Spatial Queries
+### Environmental Monitoring System
 
 ```javascript
-// Find all hexagons within a radius
-const hexagons = await holo.findWithin({
-  lat: 37.7749,
-  lng: -122.4194,
-  radius: 5000 // meters
-});
+// 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']
+};
 
-// Query data across multiple resolutions
-const aggregatedData = await holo.aggregate({
-  hexIds: hexagons,
-  resolution: 7,
-  method: 'average'
-});
+// 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);
+}
 ```
 
-### AI Processing
+### Location-Based Content System
 
 ```javascript
-// Process content with AI
-const summary = await hex.processContent({
-  processor: 'summarize',
-  options: {
-    maxLength: 100
-  }
-});
+// Initialize with AI capabilities for content summarization
+const sphere = new HoloSphere('local-content', false, 'your-openai-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']
+};
 
-// Analyze trends across regions
-const analysis = await holo.analyzeRegion({
-  hexIds: hexagons,
-  timeRange: '7d',
-  metrics: ['sentiment', 'topics']
-});
+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;
+}
 ```
 
-### Voting and Governance
+### Data Validation Example
 
 ```javascript
-// Create a proposal
-const proposal = await hex.createProposal({
-  title: 'Update Data Schema',
-  description: 'Add new fields for environmental metrics',
-  changes: {
-    schema: newSchemaDefinition
-  }
+// Strict validation with custom schema
+const sphere = new HoloSphere('validated-data', true);
+
+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
+};
+
+await sphere.setSchema('measurements', measurementSchema);
+
+// This will succeed
+await sphere.put(holon, 'measurements', {
+    id: 'measure-1',
+    value: 42.5,
+    unit: 'celsius',
+    accuracy: 0.1,
+    timestamp: Date.now()
 });
 
-// Cast a vote
-await proposal.vote({
-  support: true,
-  weight: 1.0
+// This will fail due to schema validation
+await sphere.put(holon, 'measurements', {
+    id: 'measure-2',
+    value: "invalid", // wrong type
+    extra: "field"    // not allowed
 });
 ```
 
-## Configuration
-
-HoloSphere can be configured with various options:
+## API Reference
 
+### Constructor
 ```javascript
-const config = {
-  // Network configuration
-  peers: ['https://peer1.example.com/gun', 'https://peer2.example.com/gun'],
-  
-  // Storage options
-  storage: {
-    type: 'indexeddb',
-    namespace: 'my-app'
-  },
-  
-  // AI processing configuration
-  ai: {
-    provider: 'local',
-    model: 'gpt-3.5-turbo',
-    apiKey: process.env.AI_API_KEY
-  },
-  
-  // Schema validation
-  schema: {
-    strict: true,
-    customValidators: {}
-  }
-};
-
-const holo = new HoloSphere(config);
+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
+)
 ```
 
-## Documentation
+### Core Methods
 
-For detailed documentation, please visit our [documentation site](https://docs.holons.io).
+- `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
 
-## Contributing
+## Storage Architecture
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
-- Code of Conduct
-- Development setup
-- Testing guidelines
-- Pull request process
+Data in HoloSphere is organized by:
+- **Holons**: H3 geographic indexes
+- **Lenses**: Data categories/types
+- **Items**: Individual data entries with unique IDs
 
-## Support
-
-- [GitHub Issues](https://github.com/liminalvillage/holosphere/issues)
-- [Discord Community](https://discord.gg/liminalvillage)
-
-## Roadmap
-
-- [ ] Enhanced spatial indexing algorithms
-- [ ] Additional AI model integrations
-- [ ] Improved data replication strategies
-- [ ] Extended governance mechanisms
-- [ ] Mobile SDK development
+## Dependencies
 
-## Citation
+- h3-js: Uber's H3 geospatial indexing
+- gun: Decentralized database
+- ajv: JSON Schema validation
+- openai: AI capabilities (optional)
 
-If you use HoloSphere in your research, please cite:
+## License
 
-```bibtex
-@software{holosphere2024,
-  author = {Roberto Valenti},
-  title = {HoloSphere: Decentralized Geospatial Data Management},
-  year = {2024},
-  url = {https://github.com/holosphere/holosphere}
-}
-```
+GPL-3.0-or-later
 

package/babel.config.json

@@ -0,0 +1,12 @@
+{
+  "presets": [
+    [
+      "@babel/preset-env",
+      {
+        "targets": {
+          "node": "current"
+        }
+      }
+    ]
+  ]
+} 

package/holosphere.d.ts

@@ -1,22 +1,48 @@
 declare module 'holosphere' {
     export default class HoloSphere {
-        constructor(name: string, openaikey?: string | null);
-        subscribe(hex: string, lense: string, callback: (item: any, key: string) => void): void;
-        put(hex: string, lense: string, content: any): Promise<void>;
-        delete(id: string, tag: string): Promise<void>;
-        get(hex: string, lense: string): Promise<any[]>;
-        getKey(hex: string, lense: string, key: string): Promise<any | null>;
-        getNode(hex: string, lense: string, key: string): Promise<any | null>;
-        compute(hex: string, lense: string, operation: string): Promise<void>;
-        clearlense(hex: string, lense: string): Promise<void>;
-        summarize(history: string): Promise<string>;
-        upcast(hex: string, lense: string, content: any): Promise<any>;
-        updateParent(id: string, report: string): Promise<any>;
+        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
+        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>;
+
+        // Hex Data Operations
+        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>;
         getScalespace(lat: number, lng: number): string[];
         getHexScalespace(hex: string): string[];
-        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>;
+        compute(hex: string, lens: string, operation: string): Promise<void>;
+        upcast(hex: string, lens: string, content: any): Promise<any>;
+
+        // Subscription
+        subscribe(holon: string, lens: string, callback: (data: any, key: string) => void): void;
+        subscribeGlobal(tableName: string, callback: (data: any, key: string) => void): void;
     }
 }