holosphere 2.0.0-alpha0 → 2.0.0-alpha10

package/FEATURES.md

@@ -0,0 +1,431 @@
+# Top 30 Features of HoloSphere
+
+HoloSphere is a distributed, local-first geospatial communication system that combines hexagonal spatial indexing with decentralized data storage and AI capabilities.
+
+---
+
+## 1. H3 Hexagonal Spatial Indexing
+
+Organize data by geographic location using Uber's H3 hierarchical hexagonal grid system. 16 resolution levels from continental scale (res 0) to sub-meter precision (res 15).
+
+```javascript
+const holon = h3.latLngToCell(lat, lng, resolution);
+await hs.write(holon, 'events', eventData);
+```
+
+---
+
+## 2. Multi-Backend Storage Architecture
+
+Pluggable storage backends supporting three decentralized protocols:
+
+| Backend | Protocol | Best For |
+|---------|----------|----------|
+| **Nostr** | NIP-01 events | Censorship-resistant P2P storage |
+| **GunDB** | CRDT + WebRTC | Real-time collaboration |
+| **ActivityPub** | Fediverse | Social federation |
+
+---
+
+## 3. Local-First Architecture
+
+Guaranteed delivery with offline support. Data writes to local storage first, then syncs to network when available. Never lose data due to network issues.
+
+- Outbox queue for pending operations
+- Automatic retry with exponential backoff
+- Conflict resolution via CRDTs
+
+---
+
+## 4. Hologram Federation
+
+Lightweight cross-holon data references that enable data discovery across geographic boundaries without duplicating data.
+
+```javascript
+// Create a hologram (reference) to data in another holon
+await hs.federateHolon(targetHolon, sourceHolon, lens, key);
+
+// Reading automatically resolves holograms
+const data = await hs.read(targetHolon, lens, key); // Returns source data
+```
+
+---
+
+## 5. Capability-Based Authorization
+
+Secure cross-HoloSphere authorization using cryptographic tokens:
+
+- Time-limited capability tokens with signatures
+- Scope-based permissions (holon, lens, data level)
+- Inbound/outbound capability registry
+- Delegation and revocation support
+
+---
+
+## 6. AI-Powered LLM Service
+
+Comprehensive OpenAI integration for intelligent data processing:
+
+- Text summarization and analysis
+- Automatic categorization
+- Multi-language translation
+- Sentiment analysis
+- Content moderation
+
+```javascript
+const summary = await hs.ai.summarize(longText);
+const category = await hs.ai.categorize(content, ['news', 'events', 'projects']);
+```
+
+---
+
+## 7. Vector Embeddings & Semantic Search
+
+Generate and search vector embeddings for semantic similarity:
+
+```javascript
+const embedding = await hs.ai.embed('Find renewable energy projects');
+const results = await hs.ai.semanticSearch(query, documents, { topK: 10 });
+```
+
+---
+
+## 8. Multi-Perspective AI Council
+
+Balanced decision-making through multiple AI perspectives analyzing the same question from different viewpoints (skeptic, optimist, pragmatist, etc.).
+
+```javascript
+const decision = await hs.ai.council.deliberate(
+  'Should we implement feature X?',
+  { perspectives: ['technical', 'business', 'user-experience'] }
+);
+```
+
+---
+
+## 9. Natural Language Query Interface
+
+Query your data using plain English instead of structured queries:
+
+```javascript
+const results = await hs.ai.query('Show me all events near Paris next week');
+```
+
+---
+
+## 10. Smart Contract Integration
+
+Ethereum-based fractal fund distribution with multi-chain support:
+
+| Contract | Purpose |
+|----------|---------|
+| **Splitter** | Internal/external fund split with fractal nesting |
+| **Managed** | Appreciation-based distribution |
+| **Zoned** | Tier-based geographic zone rewards |
+| **Appreciative** | Peer-to-peer appreciation tokens |
+| **Bundle** | All-in-one 2-way split with steepness curve |
+
+---
+
+## 11. Multi-Chain Support
+
+Deploy and interact with contracts on multiple EVM chains:
+
+- Ethereum Mainnet
+- Polygon
+- Arbitrum
+- Base
+- Optimism
+- Sepolia (testnet)
+
+---
+
+## 12. Real-Time Subscriptions
+
+Subscribe to data changes with callbacks for live updates:
+
+```javascript
+const sub = await hs.subscribe(holon, lens, (data, key) => {
+  console.log('Data updated:', key, data);
+});
+
+// Later: sub.unsubscribe();
+```
+
+---
+
+## 13. Schema Validation
+
+JSON Schema validation for data integrity with custom validators:
+
+```javascript
+await hs.setSchema(holon, lens, {
+  type: 'object',
+  properties: {
+    title: { type: 'string', minLength: 1 },
+    date: { type: 'string', format: 'date' }
+  },
+  required: ['title']
+});
+```
+
+---
+
+## 14. Automatic Parent Propagation
+
+Data automatically propagates to parent hexagons in the H3 hierarchy, enabling queries at any resolution level.
+
+```javascript
+// Write at resolution 9
+await hs.write('891f1d48127ffff', 'events', event);
+
+// Discoverable at resolution 7
+const events = await hs.readAll('871f1d481ffffff', 'events');
+```
+
+---
+
+## 15. Schema Extraction from Unstructured Text
+
+AI-powered extraction of structured data from free-form text:
+
+```javascript
+const structured = await hs.ai.extractSchema(
+  'Meeting tomorrow at 3pm with John about the budget review',
+  { fields: ['date', 'time', 'attendees', 'topic'] }
+);
+```
+
+---
+
+## 16. Fuzzy JSON Operations
+
+Semantic merge, diff, and union operations on JSON data:
+
+```javascript
+const merged = await hs.ai.fuzzyMerge(doc1, doc2);
+const diff = await hs.ai.fuzzyDiff(before, after);
+```
+
+---
+
+## 17. Spatial Analysis with AI
+
+Geographic pattern recognition and spatial clustering:
+
+```javascript
+const analysis = await hs.ai.analyzeSpatial(geoData, {
+  detectClusters: true,
+  findPatterns: true
+});
+```
+
+---
+
+## 18. Task Breakdown & Decomposition
+
+AI-powered hierarchical task decomposition for complex projects:
+
+```javascript
+const tasks = await hs.ai.breakdown('Build a community garden', {
+  maxDepth: 3,
+  estimateEffort: true
+});
+```
+
+---
+
+## 19. Relationship Discovery
+
+Automatically discover relationships between data entities:
+
+```javascript
+const relationships = await hs.ai.discoverRelationships(entities);
+// Returns: [{from: 'A', to: 'B', type: 'collaborates_with', confidence: 0.85}]
+```
+
+---
+
+## 20. Text-to-Speech Integration
+
+Convert text to speech with multiple voice options:
+
+```javascript
+const audio = await hs.ai.textToSpeech(text, { voice: 'alloy' });
+```
+
+---
+
+## 21. CDN-Ready Browser Bundle
+
+Direct script tag inclusion for quick web integration:
+
+```html
+<script src="https://unpkg.com/holosphere@next/dist/holosphere.cdn.js"></script>
+<script>
+  const hs = new HoloSphere({ backend: 'nostr', relays: ['wss://...'] });
+</script>
+```
+
+---
+
+## 22. Nostr Protocol Integration
+
+Full NIP-01 compliance with:
+
+- Long-lived subscriptions
+- Query deduplication
+- Intelligent caching
+- Multiple relay support
+- Automatic reconnection
+
+---
+
+## 23. GunDB Real-Time Sync
+
+CRDT-based conflict resolution with:
+
+- WebRTC peer-to-peer connections
+- Radisk persistence
+- User authentication
+- Encrypted user spaces
+
+---
+
+## 24. ActivityPub Federation
+
+Fediverse compatibility for social federation:
+
+- Actor creation and management
+- Inbox/Outbox message handling
+- Server-Sent Events for real-time updates
+- HTTP Signatures for security
+
+---
+
+## 25. Data Migration Tools
+
+Seamlessly migrate data between backends:
+
+```javascript
+const tool = new MigrationTool();
+await tool.setSource('nostr', { relays: ['wss://old.relay'] });
+await tool.setTarget('gundb', { peers: ['wss://new.peer'] });
+await tool.migrate();
+await tool.validate(); // Verify integrity
+```
+
+---
+
+## 26. Global Data Operations
+
+Store application-wide data not tied to geographic locations:
+
+```javascript
+await hs.writeGlobal('schemas', 'event-schema', schema);
+await hs.writeGlobal('config', 'app-settings', settings);
+const config = await hs.readGlobal('config', 'app-settings');
+```
+
+---
+
+## 27. Circular Reference Prevention
+
+Built-in safeguards against infinite hologram reference loops with automatic cycle detection.
+
+---
+
+## 28. TypeScript Support
+
+Comprehensive TypeScript type definitions for full IDE support:
+
+```typescript
+import { HoloSphere, Holon, Lens, HologramRef } from 'holosphere';
+
+const hs: HoloSphere = new HoloSphere(config);
+const data: MyDataType = await hs.read<MyDataType>(holon, lens, id);
+```
+
+---
+
+## 29. Contract Event Listening
+
+Real-time blockchain event monitoring:
+
+```javascript
+hs.contracts.onEvent('FundsDistributed', (event) => {
+  console.log('Distribution:', event.args.recipients, event.args.amounts);
+});
+```
+
+---
+
+## 30. Federation Advisor AI
+
+AI-powered recommendations for optimal federation strategies:
+
+```javascript
+const advice = await hs.ai.federationAdvisor({
+  sourceHolon,
+  candidateTargets,
+  dataTypes: ['events', 'projects']
+});
+// Returns recommended federation topology
+```
+
+---
+
+## Quick Start
+
+```javascript
+import { HoloSphere } from 'holosphere';
+
+// Initialize with Nostr backend
+const hs = new HoloSphere({
+  appName: 'myapp',
+  backend: 'nostr',
+  relays: ['wss://relay.damus.io', 'wss://nos.lol']
+});
+
+await hs.init();
+
+// Write geospatial data
+const holon = '891f1d48127ffff'; // H3 cell ID
+await hs.write(holon, 'events', {
+  id: 'event-1',
+  title: 'Community Meetup',
+  date: '2025-01-15'
+});
+
+// Read it back
+const event = await hs.read(holon, 'events', 'event-1');
+
+// Subscribe to changes
+await hs.subscribe(holon, 'events', (data, key) => {
+  console.log('Updated:', key);
+});
+```
+
+---
+
+## Installation
+
+```bash
+npm install holosphere@next
+```
+
+Or via CDN:
+
+```html
+<script src="https://unpkg.com/holosphere@next/dist/holosphere.cdn.js"></script>
+```
+
+---
+
+## License
+
+MIT License - Open source and free to use.
+
+---
+
+*HoloSphere: Distributed geospatial communication for a decentralized world.*

package/LICENSE

@@ -1,56 +1,43 @@
-GNU LESSER GENERAL PUBLIC LICENSE
-Version 3, 29 June 2007
+# HoloSphere - Dual Licensed
 
-Copyright © 2007 Free Software Foundation, Inc. <https://fsf.org/>
+Copyright (c) 2024-2025 Roberto Valenti
 
-Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
+This software is available under two licensing options:
 
-This version of the GNU Lesser General Public License incorporates the terms and conditions of version 3 of the GNU General Public License, supplemented by the additional permissions listed below.
+## 1. AGPL-3.0 (Open Source)
 
-0. Additional Definitions.
-As used herein, “this License” refers to version 3 of the GNU Lesser General Public License, and the “GNU GPL” refers to version 3 of the GNU General Public License.
+For open source projects and non-commercial use, HoloSphere is licensed under
+the GNU Affero General Public License version 3.0 (AGPL-3.0).
 
-“The Library” refers to a covered work governed by this License, other than an Application or a Combined Work as defined below.
+See [LICENSE-AGPL.md](LICENSE-AGPL.md) for the full license text.
 
-An “Application” is any work that makes use of an interface provided by the Library, but which is not otherwise based on the Library. Defining a subclass of a class defined by the Library is deemed a mode of using an interface provided by the Library.
+**Key requirements:**
+- You must make your source code available if you modify and distribute the software
+- Network use (SaaS) counts as distribution - you must provide source access to users
+- Derivative works must also be licensed under AGPL-3.0
 
-A “Combined Work” is a work produced by combining or linking an Application with the Library. The particular version of the Library with which the Combined Work was made is also called the “Linked Version”.
+## 2. Commercial License
 
-The “Minimal Corresponding Source” for a Combined Work means the Corresponding Source for the Combined Work, excluding any source code for portions of the Combined Work that, considered in isolation, are based on the Application, and not on the Linked Version.
+For proprietary or commercial use without AGPL obligations, a commercial license
+is available.
 
-The “Corresponding Application Code” for a Combined Work means the object code and/or source code for the Application, including any data and utility programs needed for reproducing the Combined Work from the Application, but excluding the System Libraries of the Combined Work.
+**Benefits of commercial license:**
+- Use in proprietary/closed-source applications
+- No copyleft requirements
+- No source code disclosure obligations
+- Priority support available
 
-1. Exception to Section 3 of the GNU GPL.
-You may convey a covered work under sections 3 and 4 of this License without being bound by section 3 of the GNU GPL.
+**Contact for commercial licensing:**
+- GitHub: https://github.com/liminalvillage/holosphere2/issues
+- Open an issue with the "commercial-license" label
 
-2. Conveying Modified Versions.
-If you modify a copy of the Library, and, in your modifications, a facility refers to a function or data to be supplied by an Application that uses the facility (other than as an argument passed when the facility is invoked), then you may convey a copy of the modified version:
+---
 
-a) under this License, provided that you make a good faith effort to ensure that, in the event an Application does not supply the function or data, the facility still operates, and performs whatever part of its purpose remains meaningful, or
-b) under the GNU GPL, with none of the additional permissions of this License applicable to that copy.
-3. Object Code Incorporating Material from Library Header Files.
-The object code form of an Application may incorporate material from a header file that is part of the Library. You may convey such object code under terms of your choice, provided that, if the incorporated material is not limited to numerical parameters, data structure layouts and accessors, or small macros, inline functions and templates (ten or fewer lines in length), you do both of the following:
+By using this software, you agree to the terms of one of these licenses.
 
-a) Give prominent notice with each copy of the object code that the Library is used in it and that the Library and its use are covered by this License.
-b) Accompany the object code with a copy of the GNU GPL and this license document.
-4. Combined Works.
-You may convey a Combined Work under terms of your choice that, taken together, effectively do not restrict modification of the portions of the Library contained in the Combined Work and reverse engineering for debugging such modifications, if you also do each of the following:
+If you are using this software in an open source project under AGPL-3.0
+compatible terms, no further action is required beyond compliance with the
+AGPL-3.0 license.
 
-a) Give prominent notice with each copy of the Combined Work that the Library is used in it and that the Library and its use are covered by this License.
-b) Accompany the Combined Work with a copy of the GNU GPL and this license document.
-c) For a Combined Work that displays copyright notices during execution, include the copyright notice for the Library among these notices, as well as a reference directing the user to the copies of the GNU GPL and this license document.
-d) Do one of the following:
-0) Convey the Minimal Corresponding Source under the terms of this License, and the Corresponding Application Code in a form suitable for, and under terms that permit, the user to recombine or relink the Application with a modified version of the Linked Version to produce a modified Combined Work, in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source.
-1) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (a) uses at run time a copy of the Library already present on the user's computer system, and (b) will operate properly with a modified version of the Library that is interface-compatible with the Linked Version.
-e) Provide Installation Information, but only if you would otherwise be required to provide such information under section 6 of the GNU GPL, and only to the extent that such information is necessary to install and execute a modified version of the Combined Work produced by recombining or relinking the Application with a modified version of the Linked Version. (If you use option 4d0, the Installation Information must accompany the Minimal Corresponding Source and Corresponding Application Code. If you use option 4d1, you must provide the Installation Information in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source.)
-5. Combined Libraries.
-You may place library facilities that are a work based on the Library side by side in a single library together with other library facilities that are not Applications and are not covered by this License, and convey such a combined library under terms of your choice, if you do both of the following:
-
-a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities, conveyed under the terms of this License.
-b) Give prominent notice with the combined library that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work.
-6. Revised Versions of the GNU Lesser General Public License.
-The Free Software Foundation may publish revised and/or new versions of the GNU Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
-
-Each version is given a distinguishing version number. If the Library as you received it specifies that a certain numbered version of the GNU Lesser General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that published version or of any later version published by the Free Software Foundation. If the Library as you received it does not specify a version number of the GNU Lesser General Public License, you may choose any version of the GNU Lesser General Public License ever published by the Free Software Foundation.
-
-If the Library as you received it specifies that a proxy can decide whether future versions of the GNU Lesser General Public License shall apply, that proxy's public statement of acceptance of any version is permanent authorization for you to choose that version for the Library.
+If you need a commercial license, please contact us before using this software
+in a proprietary context.