# ZeroModel Intelligence (ZeroModel)
[](https://badge.fury.io/py/zeromodel)
[](https://opensource.org/licenses/MIT)
**ZeroModel Intelligence** is a paradigm-shifting approach that embeds decision logic into the *structure* of data itself. Instead of making models smarter, ZeroModel makes data structures intelligent.
> **The intelligence isn't in the processing—it's in the data structure itself.**
## 🧠 Core Concept
ZeroModel transforms high-dimensional policy evaluation data into spatially-optimized **Visual Policy Maps (VPMs)** where:
- **Position = Importance** (top-left = most relevant)
- **Color = Value** (darker = higher priority)
- **Structure = Task logic** (spatial organization encodes decision workflow based on user-defined SQL)
This enables **zero-model intelligence** on devices with <25KB memory and unlocks **Visual Symbolic Reasoning**.
## 🚀 Quick Start
```bash
pip install zeromodel
```
```python
from zeromodel.core import ZeroModel
import numpy as np
# 1. Prepare your data (documents × metrics)
# Example: 100 items scored on 5 criteria
score_matrix = np.random.rand(100, 5)
metric_names = ["uncertainty", "size", "quality", "novelty", "coherence"]
# 2. Initialize ZeroModel
zeromodel = ZeroModel(metric_names)
# 3. Define your task using SQL and process the data in one step
# The intelligence comes from how you sort the data for your task.
sql_task = "SELECT * FROM virtual_index ORDER BY quality DESC, uncertainty ASC"
# Process data for the task. This handles normalization and spatial organization.
# Use nonlinearity hints for complex tasks (e.g., XOR-like patterns).
zeromodel.prepare(score_matrix, sql_task, nonlinearity_hint='auto')
# 4. Get the Visual Policy Map (VPM) - a structured image
vpm = zeromodel.encode() # Returns a NumPy array (H x W x 3)
# 5. Make decisions by inspecting the structured VPM
doc_idx, relevance = zeromodel.get_decision()
print(f"Top document index: {doc_idx}, Relevance score: {relevance:.4f}")
# 6. For edge devices: get a small, critical tile
tile_bytes = zeromodel.get_critical_tile(tile_size=3) # Returns compact bytes
```
## 🧬 Hierarchical Reasoning
Handle large datasets and multi-resolution decisions with `HierarchicalVPM`:
```python
from zeromodel.hierarchical import HierarchicalVPM
# Create a hierarchical structure (e.g., 3 levels)
hvpm = HierarchicalVPM(metric_names, num_levels=3, zoom_factor=3, precision=16)
# Process data with the same SQL task
hvpm.process(score_matrix, sql_task) # Internally uses ZeroModel.prepare
# Access different levels of detail
base_level_vpm = hvpm.get_level(2)["vpm"] # Level 2: Most detailed
strategic_vpm = hvpm.get_level(0)["vpm"] # Level 0: Most abstract
# Get a tile from a specific level for an edge device
edge_tile_bytes = hvpm.get_tile(level_index=0, width=3, height=3)
# Make a decision (defaults to most detailed level)
level, doc_idx, relevance = hvpm.get_decision()
```
## 🔮 Visual Symbolic Reasoning
Combine VPMs like logic gates to create new, complex decision criteria:
```python
from zeromodel.vpm.logic import vpm_and, vpm_or, vpm_not, vpm_query_top_left
# Prepare VPMs for different sub-tasks
high_quality_model = ZeroModel(metric_names)
high_quality_model.prepare(score_matrix, "SELECT * FROM virtual_index ORDER BY quality DESC")
high_quality_vpm = high_quality_model.encode()
low_uncertainty_model = ZeroModel(metric_names)
low_uncertainty_model.prepare(score_matrix, "SELECT * FROM virtual_index ORDER BY uncertainty ASC")
low_uncertainty_vpm = low_uncertainty_model.encode()
# Compose VPMs: Find items that are High Quality AND Low Uncertainty
# The result is a new VPM representing this combined concept.
good_and_cert_vpm = vpm_and(high_quality_vpm, low_uncertainty_vpm)
# Query the composed VPM
composite_score = vpm_query_top_left(good_and_cert_vpm, context_size=3)
print(f"Score for 'High Quality AND Low Uncertainty' items: {composite_score:.4f}")
# This enables complex reasoning: (A AND NOT B) OR (C AND D) as VPM operations.
```
## 💡 Edge Device Example (Pseudocode)
Tiny devices can make intelligent decisions using minimal code by processing small VPM tiles.
```python
# --- On a powerful server ---
hvpm = HierarchicalVPM(metric_names)
hvpm.process(large_score_matrix, "SELECT * ORDER BY my_metric DESC")
tile_bytes_level_0 = hvpm.get_tile(level_index=0, width=3, height=3)
send_to_edge_device(tile_bytes_level_0)
# --- On the tiny edge device (e.g., microcontroller) ---
def process_tile_simple(tile_bytes):
# Parse 4-byte header: 16-bit little-endian width, height
if len(tile_bytes) < 5:
return 0
width = tile_bytes[0] | (tile_bytes[1] << 8)
height = tile_bytes[2] | (tile_bytes[3] << 8)
# Simple decision: check the very first pixel's Red channel
# (Assumes uint8 RGB layout [R, G, B, R, G, B, ...])
first_pixel_red_value = tile_bytes[4]
return 1 if first_pixel_red_value < 128 else 0
# result = process_tile_simple(received_tile_bytes)
# if result == 1: perform_action()
```
## 📚 Running Tests
Ensure you have `pytest` installed (`pip install pytest`).
```bash
# Run all tests
pytest tests/ -v
# Run a specific test file
pytest tests/test_core.py -v
# Run a specific test function
pytest tests/test_xor.py::test_xor_validation -v -s
```
## 🌐 Website
Check out our website at [zeromi.org](https://zeromodel.org) for tutorials, examples, and community resources.
## 📄 Citation
If you use ZeroModel in your research, please cite:
```text
@article{zeromodel2025,
title={Zero-Model Intelligence: Spatially-Optimized Decision Maps for Resource-Constrained AI},
author={Ernan Hughes},
journal={arXiv preprint arXiv:XXXX.XXXXX},
year={2025}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/ernanhughes/zeromodel",
"name": "ZeroModel",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "ai, machine learning, explainability, vpm, provenance",
"author": "Ernan Hughes",
"author_email": "ernanhughes@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8e/e1/3f24e27240c1dadef43d8207d5fa5250c1b98976d412fea8cf8985ff7403/zeromodel-1.0.7.tar.gz",
"platform": null,
"description": "# ZeroModel Intelligence (ZeroModel)\r\n\r\n[](https://badge.fury.io/py/zeromodel)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\n**ZeroModel Intelligence** is a paradigm-shifting approach that embeds decision logic into the *structure* of data itself. Instead of making models smarter, ZeroModel makes data structures intelligent.\r\n\r\n> **The intelligence isn't in the processing\u2014it's in the data structure itself.**\r\n\r\n## \ud83e\udde0 Core Concept\r\n\r\nZeroModel transforms high-dimensional policy evaluation data into spatially-optimized **Visual Policy Maps (VPMs)** where:\r\n\r\n- **Position = Importance** (top-left = most relevant)\r\n- **Color = Value** (darker = higher priority)\r\n- **Structure = Task logic** (spatial organization encodes decision workflow based on user-defined SQL)\r\n\r\nThis enables **zero-model intelligence** on devices with <25KB memory and unlocks **Visual Symbolic Reasoning**.\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n```bash\r\npip install zeromodel\r\n```\r\n\r\n```python\r\nfrom zeromodel.core import ZeroModel\r\nimport numpy as np\r\n\r\n# 1. Prepare your data (documents \u00d7 metrics)\r\n# Example: 100 items scored on 5 criteria\r\nscore_matrix = np.random.rand(100, 5)\r\nmetric_names = [\"uncertainty\", \"size\", \"quality\", \"novelty\", \"coherence\"]\r\n\r\n# 2. Initialize ZeroModel\r\nzeromodel = ZeroModel(metric_names)\r\n\r\n# 3. Define your task using SQL and process the data in one step\r\n# The intelligence comes from how you sort the data for your task.\r\nsql_task = \"SELECT * FROM virtual_index ORDER BY quality DESC, uncertainty ASC\"\r\n\r\n# Process data for the task. This handles normalization and spatial organization.\r\n# Use nonlinearity hints for complex tasks (e.g., XOR-like patterns).\r\nzeromodel.prepare(score_matrix, sql_task, nonlinearity_hint='auto')\r\n\r\n# 4. Get the Visual Policy Map (VPM) - a structured image\r\nvpm = zeromodel.encode() # Returns a NumPy array (H x W x 3)\r\n\r\n# 5. Make decisions by inspecting the structured VPM\r\ndoc_idx, relevance = zeromodel.get_decision()\r\nprint(f\"Top document index: {doc_idx}, Relevance score: {relevance:.4f}\")\r\n\r\n# 6. For edge devices: get a small, critical tile\r\ntile_bytes = zeromodel.get_critical_tile(tile_size=3) # Returns compact bytes\r\n```\r\n\r\n## \ud83e\uddec Hierarchical Reasoning\r\n\r\nHandle large datasets and multi-resolution decisions with `HierarchicalVPM`:\r\n\r\n```python\r\nfrom zeromodel.hierarchical import HierarchicalVPM\r\n\r\n# Create a hierarchical structure (e.g., 3 levels)\r\nhvpm = HierarchicalVPM(metric_names, num_levels=3, zoom_factor=3, precision=16)\r\n\r\n# Process data with the same SQL task\r\nhvpm.process(score_matrix, sql_task) # Internally uses ZeroModel.prepare\r\n\r\n# Access different levels of detail\r\nbase_level_vpm = hvpm.get_level(2)[\"vpm\"] # Level 2: Most detailed\r\nstrategic_vpm = hvpm.get_level(0)[\"vpm\"] # Level 0: Most abstract\r\n\r\n# Get a tile from a specific level for an edge device\r\nedge_tile_bytes = hvpm.get_tile(level_index=0, width=3, height=3)\r\n\r\n# Make a decision (defaults to most detailed level)\r\nlevel, doc_idx, relevance = hvpm.get_decision()\r\n```\r\n\r\n## \ud83d\udd2e Visual Symbolic Reasoning\r\n\r\nCombine VPMs like logic gates to create new, complex decision criteria:\r\n\r\n```python\r\nfrom zeromodel.vpm.logic import vpm_and, vpm_or, vpm_not, vpm_query_top_left\r\n\r\n# Prepare VPMs for different sub-tasks\r\nhigh_quality_model = ZeroModel(metric_names)\r\nhigh_quality_model.prepare(score_matrix, \"SELECT * FROM virtual_index ORDER BY quality DESC\")\r\nhigh_quality_vpm = high_quality_model.encode()\r\n\r\nlow_uncertainty_model = ZeroModel(metric_names)\r\nlow_uncertainty_model.prepare(score_matrix, \"SELECT * FROM virtual_index ORDER BY uncertainty ASC\")\r\nlow_uncertainty_vpm = low_uncertainty_model.encode()\r\n\r\n# Compose VPMs: Find items that are High Quality AND Low Uncertainty\r\n# The result is a new VPM representing this combined concept.\r\ngood_and_cert_vpm = vpm_and(high_quality_vpm, low_uncertainty_vpm)\r\n\r\n# Query the composed VPM\r\ncomposite_score = vpm_query_top_left(good_and_cert_vpm, context_size=3)\r\nprint(f\"Score for 'High Quality AND Low Uncertainty' items: {composite_score:.4f}\")\r\n\r\n# This enables complex reasoning: (A AND NOT B) OR (C AND D) as VPM operations.\r\n```\r\n\r\n## \ud83d\udca1 Edge Device Example (Pseudocode)\r\n\r\nTiny devices can make intelligent decisions using minimal code by processing small VPM tiles.\r\n\r\n```python\r\n# --- On a powerful server ---\r\nhvpm = HierarchicalVPM(metric_names)\r\nhvpm.process(large_score_matrix, \"SELECT * ORDER BY my_metric DESC\")\r\ntile_bytes_level_0 = hvpm.get_tile(level_index=0, width=3, height=3)\r\nsend_to_edge_device(tile_bytes_level_0)\r\n\r\n# --- On the tiny edge device (e.g., microcontroller) ---\r\ndef process_tile_simple(tile_bytes):\r\n # Parse 4-byte header: 16-bit little-endian width, height\r\n if len(tile_bytes) < 5:\r\n return 0\r\n width = tile_bytes[0] | (tile_bytes[1] << 8)\r\n height = tile_bytes[2] | (tile_bytes[3] << 8)\r\n # Simple decision: check the very first pixel's Red channel\r\n # (Assumes uint8 RGB layout [R, G, B, R, G, B, ...])\r\n first_pixel_red_value = tile_bytes[4]\r\n return 1 if first_pixel_red_value < 128 else 0\r\n\r\n# result = process_tile_simple(received_tile_bytes)\r\n# if result == 1: perform_action()\r\n```\r\n\r\n## \ud83d\udcda Running Tests\r\n\r\nEnsure you have `pytest` installed (`pip install pytest`).\r\n\r\n```bash\r\n# Run all tests\r\npytest tests/ -v\r\n\r\n# Run a specific test file\r\npytest tests/test_core.py -v\r\n\r\n# Run a specific test function\r\npytest tests/test_xor.py::test_xor_validation -v -s\r\n```\r\n\r\n## \ud83c\udf10 Website\r\n\r\nCheck out our website at [zeromi.org](https://zeromodel.org) for tutorials, examples, and community resources.\r\n\r\n## \ud83d\udcc4 Citation\r\n\r\nIf you use ZeroModel in your research, please cite:\r\n\r\n```text\r\n@article{zeromodel2025,\r\n title={Zero-Model Intelligence: Spatially-Optimized Decision Maps for Resource-Constrained AI},\r\n author={Ernan Hughes},\r\n journal={arXiv preprint arXiv:XXXX.XXXXX},\r\n year={2025}\r\n}\r\n```\r\n",
"bugtrack_url": null,
"license": null,
"summary": "ZeroModel: Data-centric AI with visual policy maps",
"version": "1.0.7",
"project_urls": {
"Homepage": "https://github.com/ernanhughes/zeromodel"
},
"split_keywords": [
"ai",
" machine learning",
" explainability",
" vpm",
" provenance"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3f5e3a8431096f720b31e14eaf559c2a5966807c0a96dc184e78657d40438386",
"md5": "950e222087993fcd959ffe8332e0490d",
"sha256": "50351117b04d91593c037143cda2382a3f39d2a26f1776174be1121dbbe08a5b"
},
"downloads": -1,
"filename": "zeromodel-1.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "950e222087993fcd959ffe8332e0490d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 387653,
"upload_time": "2025-09-16T19:31:00",
"upload_time_iso_8601": "2025-09-16T19:31:00.295924Z",
"url": "https://files.pythonhosted.org/packages/3f/5e/3a8431096f720b31e14eaf559c2a5966807c0a96dc184e78657d40438386/zeromodel-1.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8ee13f24e27240c1dadef43d8207d5fa5250c1b98976d412fea8cf8985ff7403",
"md5": "c667fae27dec162e25f36d9658ac76c0",
"sha256": "b31c4125840fa711984fe11116da66d62d9447965d121fb94a6b711788f9d80d"
},
"downloads": -1,
"filename": "zeromodel-1.0.7.tar.gz",
"has_sig": false,
"md5_digest": "c667fae27dec162e25f36d9658ac76c0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 300899,
"upload_time": "2025-09-16T19:31:01",
"upload_time_iso_8601": "2025-09-16T19:31:01.794567Z",
"url": "https://files.pythonhosted.org/packages/8e/e1/3f24e27240c1dadef43d8207d5fa5250c1b98976d412fea8cf8985ff7403/zeromodel-1.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-16 19:31:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ernanhughes",
"github_project": "zeromodel",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "zeromodel"
}
JSON
