nexora-py 1.0.0__tar.gz

nexora_py-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Teja Priyan and NEXORA Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nexora_py-1.0.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: nexora-py
+Version: 1.0.0
+Summary: A modular, local-first Python runtime: events, plugins, state, adaptive interfaces, memory, timeline rewind, observability, screen perception, procedural worlds, and sandboxed agents.
+Author: NEXORA Contributors
+Author-email: Teja Priyan <teja1616150@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/TejaPriyan/Nexora
+Project-URL: Documentation, https://github.com/TejaPriyan/Nexora/tree/main/docs
+Project-URL: Repository, https://github.com/TejaPriyan/Nexora.git
+Project-URL: Issues, https://github.com/TejaPriyan/Nexora/issues
+Keywords: runtime,events,plugins,local-first,privacy,agents,observability
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: ghost
+Requires-Dist: rich>=13.0; extra == "ghost"
+Provides-Extra: world
+Requires-Dist: pygame>=2.5; extra == "world"
+Provides-Extra: vision
+Requires-Dist: pillow>=10.0; extra == "vision"
+Requires-Dist: mss>=9.0; extra == "vision"
+Provides-Extra: ai
+Requires-Dist: numpy>=1.24; extra == "ai"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Provides-Extra: all
+Requires-Dist: rich>=13.0; extra == "all"
+Requires-Dist: pygame>=2.5; extra == "all"
+Requires-Dist: pillow>=10.0; extra == "all"
+Requires-Dist: mss>=9.0; extra == "all"
+Requires-Dist: numpy>=1.24; extra == "all"
+Dynamic: license-file
+
+# NEXORA
+
+**One Python ecosystem. Many capabilities. Completely modular. Local-first. Privacy-first. Open-source.**
+
+NEXORA is a modular Python runtime. The long-term vision is to give ordinary
+Python applications new capabilities -- automatic interfaces, visual
+application/world representations, adaptive interfaces, persistent
+application memory, state history and rewind, screen/computer perception,
+live application observation, interactive world generation, and controlled
+AI-agent execution -- all built on one small, shared runtime.
+
+This is **not** meant to become another chatbot wrapper, terminal UI
+library, game engine, vector database wrapper, agent wrapper, or
+automation library on its own. Each capability is a module; the modules
+share one event system, one state model, one security/privacy layer, and
+one CLI.
+
+> **Status: v1.0.0 (Complete Platform Release).** All 10 milestones are fully implemented and verified:
+> NEXORA Core, **GhostUI** (Milestone 1), **CodeWorld** (Milestone 2), **MoodUI** (Milestone 3),
+> **Recall** (Milestone 4), **TimeLoop** (Milestone 5), **Shadow** (Milestone 6),
+> **ScreenMind** (Milestone 7), **WorldForge** (Milestone 8), **AgentBox** (Milestone 9),
+> and **Module Interoperability** (Milestone 10) -- see [What's implemented today](#whats-implemented-today)
+> and [docs/ROADMAP.md](docs/ROADMAP.md). Every module communicates strictly through the shared EventBus and State with zero cross-module imports.
+
+---
+
+## Install
+
+```bash
+pip install nexora-py
+```
+
+The base install is dependency-free (Python stdlib only). Feature modules
+pull in extras as needed, e.g.:
+
+```bash
+pip install nexora-py[ghost]    # rich (GhostUI automatic terminal interfaces)
+pip install nexora-py[world]    # pygame (CodeWorld 2D entity visualization)
+pip install nexora-py[vision]   # pillow + mss (ScreenMind screen perception)
+pip install nexora-py[ai]       # numpy, for numerical operations
+pip install nexora-py[all]      # everything above
+```
+
+*(Note: The package installs as `nexora-py`, and is imported in Python directly as `nexora`, e.g. `import nexora` or `from nexora import App`.)*
+
+## Quickstart
+
+```python
+from nexora import App
+
+app = App()
+
+@app.task
+def process_data():
+    print("processing...")
+
+app.run()
+```
+
+Every task call automatically emits `task.started` / `task.completed` /
+`task.failed` events on the app's event bus, which anything else in the
+process can subscribe to:
+
+```python
+@app.bus.on("task.completed")
+def on_done(event):
+    print(f"{event.payload['task']} took {event.payload['duration_seconds']:.3f}s")
+```
+
+See [`examples/`](examples/) for runnable demonstrations:
+- **`showcase_all.py`**: **Master live showcase of all 10 milestones in action!**
+- `ghost_ui_demo.py`: GhostUI automatic terminal UI dashboards, logs, and metrics
+- `codeworld_demo.py`: CodeWorld 2D entity visualization and spatial topology
+- `mood_ui_demo.py`: MoodUI interaction-aware adaptive interfaces and friction detection
+- `recall_demo.py`: Recall persistent application memory with secret redaction
+- `timeloop_demo.py`: TimeLoop runtime state checkpoints, rewind, and structural diff
+- `shadow_demo.py`: Shadow live observability, high-resolution timing, and error tracking
+- `vision_demo.py`: ScreenMind explicitly-permissioned screen perception
+- `worldforge_demo.py`: WorldForge interactive procedural world generation
+- `agentbox_demo.py`: AgentBox sandboxed autonomous agent execution
+- `events_demo.py`: Using `EventBus` standalone
+- `state_and_storage_demo.py`: Observable state + local persistence
+
+## CLI
+
+```bash
+nexora version     # print the installed version
+nexora doctor       # check which optional extras are installed
+nexora init myapp   # scaffold a new NEXORA app
+```
+
+## What's implemented today
+
+| Layer | Status | Module |
+|---|---|---|
+| Event system | ✅ implemented | `nexora.events` (`EventBus`, `Event`) |
+| State | ✅ implemented | `nexora.state` (`State`) |
+| Configuration | ✅ implemented | `nexora.config` (`Config`) |
+| Security / privacy | ✅ implemented | `nexora.security` (`PermissionManager`, `SecretRedactor`) |
+| Local storage | ✅ implemented | `nexora.storage` (`LocalStore`, SQLite-backed) |
+| Plugin architecture | ✅ implemented | `nexora.plugins` (`Plugin`, feature registry) |
+| App / tasks | ✅ implemented | `nexora.App` |
+| CLI | ✅ implemented | `nexora` command (`version`, `doctor`, `init`) |
+| GhostUI | ✅ implemented | `nexora.ghost` (`GhostPlugin`, `GhostUI`, terminal interfaces via `rich`) |
+| CodeWorld | ✅ implemented | `nexora.world` (`WorldPlugin`, `CodeWorld`, 2D entity visualization via `pygame`) |
+| MoodUI (adaptive) | ✅ implemented | `nexora.adaptive` (`AdaptivePlugin`, `MoodUI`, interaction-aware states) |
+| Recall (memory) | ✅ implemented | `nexora.memory` (`MemoryPlugin`, `Recall`, structured memory via `LocalStore`) |
+| TimeLoop (timeline) | ✅ implemented | `nexora.timeline` (`TimelinePlugin`, `TimeLoop`, state checkpoint & rewind) |
+| Shadow (observability) | ✅ implemented | `nexora.shadow` (`ShadowPlugin`, `Shadow`, genuine execution timing & errors) |
+| ScreenMind (vision) | ✅ implemented | `nexora.vision` (`VisionPlugin`, `ScreenMind`, explicitly-permissioned screen perception) |
+| WorldForge | ✅ implemented | `nexora.worldforge` (`WorldForgePlugin`, `WorldForge`, procedural interactive worlds) |
+| AgentBox | ✅ implemented | `nexora.agentbox` (`AgentBoxPlugin`, `AgentBox`, sandboxed execution for autonomous agents) |
+
+### Modular Feature Activation
+
+Every feature is strictly optional and isolated. You activate only the modules your application needs:
+
+```python
+from nexora import App
+
+# Opt in to only the features you want:
+app = App(features=["ghost", "memory", "shadow"])
+
+# Access feature APIs directly on the app instance:
+app.memory.remember("server_config", {"port": 8080})
+app.ghost.log("App initialized with memory & shadow observability.")
+```
+
+If an app requests a planned or unregistered feature that is not available, NEXORA raises a clear `NotImplementedError` rather than silently failing:
+
+```python
+app = App(features=["unbuilt_custom_plugin"])
+app.run()
+# NotImplementedError: NEXORA feature 'unbuilt_custom_plugin' is not registered...
+```
+
+See [docs/ROADMAP.md](docs/ROADMAP.md) for the complete roadmap and
+[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for how the layers fit
+together.
+
+## Privacy principles
+
+NEXORA is local-first by default:
+
+- `Config.telemetry` and `Config.cloud_sync` default to `False`.
+- `nexora.security.PermissionManager` grants nothing by default -- every
+  privacy-sensitive capability future modules add (screen capture, agent
+  file/system access, etc.) must be explicitly granted per scope, and
+  every grant/revoke is recorded in an in-process audit trail.
+- `nexora.storage.LocalStore` is SQLite-backed, on-disk, and makes no
+  network calls.
+- `nexora.security.SecretRedactor` exists so state/timeline snapshots
+  never blindly serialize obvious secret-shaped keys --
+  this is a best-effort heuristic, not a guarantee, and callers should
+  always add known-sensitive fields explicitly.
+
+See [SECURITY.md](SECURITY.md) for the full policy and responsible
+disclosure process.
+
+## Development
+
+```bash
+git clone https://github.com/TejaPriyan/Nexora.git
+cd Nexora
+pip install -e ".[dev]"
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how modules are added
+incrementally.
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

nexora_py-1.0.0/README.md

@@ -0,0 +1,174 @@
+# NEXORA
+
+**One Python ecosystem. Many capabilities. Completely modular. Local-first. Privacy-first. Open-source.**
+
+NEXORA is a modular Python runtime. The long-term vision is to give ordinary
+Python applications new capabilities -- automatic interfaces, visual
+application/world representations, adaptive interfaces, persistent
+application memory, state history and rewind, screen/computer perception,
+live application observation, interactive world generation, and controlled
+AI-agent execution -- all built on one small, shared runtime.
+
+This is **not** meant to become another chatbot wrapper, terminal UI
+library, game engine, vector database wrapper, agent wrapper, or
+automation library on its own. Each capability is a module; the modules
+share one event system, one state model, one security/privacy layer, and
+one CLI.
+
+> **Status: v1.0.0 (Complete Platform Release).** All 10 milestones are fully implemented and verified:
+> NEXORA Core, **GhostUI** (Milestone 1), **CodeWorld** (Milestone 2), **MoodUI** (Milestone 3),
+> **Recall** (Milestone 4), **TimeLoop** (Milestone 5), **Shadow** (Milestone 6),
+> **ScreenMind** (Milestone 7), **WorldForge** (Milestone 8), **AgentBox** (Milestone 9),
+> and **Module Interoperability** (Milestone 10) -- see [What's implemented today](#whats-implemented-today)
+> and [docs/ROADMAP.md](docs/ROADMAP.md). Every module communicates strictly through the shared EventBus and State with zero cross-module imports.
+
+---
+
+## Install
+
+```bash
+pip install nexora-py
+```
+
+The base install is dependency-free (Python stdlib only). Feature modules
+pull in extras as needed, e.g.:
+
+```bash
+pip install nexora-py[ghost]    # rich (GhostUI automatic terminal interfaces)
+pip install nexora-py[world]    # pygame (CodeWorld 2D entity visualization)
+pip install nexora-py[vision]   # pillow + mss (ScreenMind screen perception)
+pip install nexora-py[ai]       # numpy, for numerical operations
+pip install nexora-py[all]      # everything above
+```
+
+*(Note: The package installs as `nexora-py`, and is imported in Python directly as `nexora`, e.g. `import nexora` or `from nexora import App`.)*
+
+## Quickstart
+
+```python
+from nexora import App
+
+app = App()
+
+@app.task
+def process_data():
+    print("processing...")
+
+app.run()
+```
+
+Every task call automatically emits `task.started` / `task.completed` /
+`task.failed` events on the app's event bus, which anything else in the
+process can subscribe to:
+
+```python
+@app.bus.on("task.completed")
+def on_done(event):
+    print(f"{event.payload['task']} took {event.payload['duration_seconds']:.3f}s")
+```
+
+See [`examples/`](examples/) for runnable demonstrations:
+- **`showcase_all.py`**: **Master live showcase of all 10 milestones in action!**
+- `ghost_ui_demo.py`: GhostUI automatic terminal UI dashboards, logs, and metrics
+- `codeworld_demo.py`: CodeWorld 2D entity visualization and spatial topology
+- `mood_ui_demo.py`: MoodUI interaction-aware adaptive interfaces and friction detection
+- `recall_demo.py`: Recall persistent application memory with secret redaction
+- `timeloop_demo.py`: TimeLoop runtime state checkpoints, rewind, and structural diff
+- `shadow_demo.py`: Shadow live observability, high-resolution timing, and error tracking
+- `vision_demo.py`: ScreenMind explicitly-permissioned screen perception
+- `worldforge_demo.py`: WorldForge interactive procedural world generation
+- `agentbox_demo.py`: AgentBox sandboxed autonomous agent execution
+- `events_demo.py`: Using `EventBus` standalone
+- `state_and_storage_demo.py`: Observable state + local persistence
+
+## CLI
+
+```bash
+nexora version     # print the installed version
+nexora doctor       # check which optional extras are installed
+nexora init myapp   # scaffold a new NEXORA app
+```
+
+## What's implemented today
+
+| Layer | Status | Module |
+|---|---|---|
+| Event system | ✅ implemented | `nexora.events` (`EventBus`, `Event`) |
+| State | ✅ implemented | `nexora.state` (`State`) |
+| Configuration | ✅ implemented | `nexora.config` (`Config`) |
+| Security / privacy | ✅ implemented | `nexora.security` (`PermissionManager`, `SecretRedactor`) |
+| Local storage | ✅ implemented | `nexora.storage` (`LocalStore`, SQLite-backed) |
+| Plugin architecture | ✅ implemented | `nexora.plugins` (`Plugin`, feature registry) |
+| App / tasks | ✅ implemented | `nexora.App` |
+| CLI | ✅ implemented | `nexora` command (`version`, `doctor`, `init`) |
+| GhostUI | ✅ implemented | `nexora.ghost` (`GhostPlugin`, `GhostUI`, terminal interfaces via `rich`) |
+| CodeWorld | ✅ implemented | `nexora.world` (`WorldPlugin`, `CodeWorld`, 2D entity visualization via `pygame`) |
+| MoodUI (adaptive) | ✅ implemented | `nexora.adaptive` (`AdaptivePlugin`, `MoodUI`, interaction-aware states) |
+| Recall (memory) | ✅ implemented | `nexora.memory` (`MemoryPlugin`, `Recall`, structured memory via `LocalStore`) |
+| TimeLoop (timeline) | ✅ implemented | `nexora.timeline` (`TimelinePlugin`, `TimeLoop`, state checkpoint & rewind) |
+| Shadow (observability) | ✅ implemented | `nexora.shadow` (`ShadowPlugin`, `Shadow`, genuine execution timing & errors) |
+| ScreenMind (vision) | ✅ implemented | `nexora.vision` (`VisionPlugin`, `ScreenMind`, explicitly-permissioned screen perception) |
+| WorldForge | ✅ implemented | `nexora.worldforge` (`WorldForgePlugin`, `WorldForge`, procedural interactive worlds) |
+| AgentBox | ✅ implemented | `nexora.agentbox` (`AgentBoxPlugin`, `AgentBox`, sandboxed execution for autonomous agents) |
+
+### Modular Feature Activation
+
+Every feature is strictly optional and isolated. You activate only the modules your application needs:
+
+```python
+from nexora import App
+
+# Opt in to only the features you want:
+app = App(features=["ghost", "memory", "shadow"])
+
+# Access feature APIs directly on the app instance:
+app.memory.remember("server_config", {"port": 8080})
+app.ghost.log("App initialized with memory & shadow observability.")
+```
+
+If an app requests a planned or unregistered feature that is not available, NEXORA raises a clear `NotImplementedError` rather than silently failing:
+
+```python
+app = App(features=["unbuilt_custom_plugin"])
+app.run()
+# NotImplementedError: NEXORA feature 'unbuilt_custom_plugin' is not registered...
+```
+
+See [docs/ROADMAP.md](docs/ROADMAP.md) for the complete roadmap and
+[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for how the layers fit
+together.
+
+## Privacy principles
+
+NEXORA is local-first by default:
+
+- `Config.telemetry` and `Config.cloud_sync` default to `False`.
+- `nexora.security.PermissionManager` grants nothing by default -- every
+  privacy-sensitive capability future modules add (screen capture, agent
+  file/system access, etc.) must be explicitly granted per scope, and
+  every grant/revoke is recorded in an in-process audit trail.
+- `nexora.storage.LocalStore` is SQLite-backed, on-disk, and makes no
+  network calls.
+- `nexora.security.SecretRedactor` exists so state/timeline snapshots
+  never blindly serialize obvious secret-shaped keys --
+  this is a best-effort heuristic, not a guarantee, and callers should
+  always add known-sensitive fields explicitly.
+
+See [SECURITY.md](SECURITY.md) for the full policy and responsible
+disclosure process.
+
+## Development
+
+```bash
+git clone https://github.com/TejaPriyan/Nexora.git
+cd Nexora
+pip install -e ".[dev]"
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how modules are added
+incrementally.
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

nexora_py-1.0.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nexora-py"
+version = "1.0.0"
+description = "A modular, local-first Python runtime: events, plugins, state, adaptive interfaces, memory, timeline rewind, observability, screen perception, procedural worlds, and sandboxed agents."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Teja Priyan", email = "teja1616150@gmail.com" }, { name = "NEXORA Contributors" }]
+keywords = ["runtime", "events", "plugins", "local-first", "privacy", "agents", "observability"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+# The base install is intentionally dependency-free (stdlib only).
+dependencies = []
+
+[project.optional-dependencies]
+ghost = ["rich>=13.0"]
+world = ["pygame>=2.5"]
+vision = ["pillow>=10.0", "mss>=9.0"]
+ai = ["numpy>=1.24"]
+dev = ["pytest>=7.4", "pytest-cov>=4.1"]
+all = ["rich>=13.0", "pygame>=2.5", "pillow>=10.0", "mss>=9.0", "numpy>=1.24"]
+
+[project.scripts]
+nexora = "nexora.cli.main:main"
+
+[project.urls]
+Homepage = "https://github.com/TejaPriyan/Nexora"
+Documentation = "https://github.com/TejaPriyan/Nexora/tree/main/docs"
+Repository = "https://github.com/TejaPriyan/Nexora.git"
+Issues = "https://github.com/TejaPriyan/Nexora/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+nexora = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

nexora_py-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nexora_py-1.0.0/src/nexora/__init__.py

@@ -0,0 +1,21 @@
+from ._version import __version__
+from .app import App
+from .config import Config
+from .events import Event, EventBus
+from .runtime import Runtime
+from .security import PermissionManager, SecretRedactor
+from .state import State
+from .storage import LocalStore
+
+__all__ = [
+    "__version__",
+    "App",
+    "Config",
+    "Event",
+    "EventBus",
+    "Runtime",
+    "State",
+    "PermissionManager",
+    "SecretRedactor",
+    "LocalStore",
+]

nexora_py-1.0.0/src/nexora/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

nexora_py-1.0.0/src/nexora/adaptive/__init__.py

@@ -0,0 +1,24 @@
+"""MoodUI (adaptive interfaces) -- Milestone 3 of NEXORA.
+
+Derives interaction-aware states (NORMAL, FAST, DIFFICULTY_HIGH, INACTIVE,
+ERROR_HEAVY) purely from observable signals -- repeated/failed actions,
+navigation loops, help requests, inactivity -- with explicit opt-in
+and no hidden monitoring. Strictly avoids emotion-detection claims.
+"""
+
+from .engine import AdaptiveEngine
+from .models import AdaptiveConfig, InteractionSignal, InteractionState, StateTransition
+from .plugin import AdaptivePlugin, MoodUI
+
+STATUS = "implemented"
+
+__all__ = [
+    "AdaptivePlugin",
+    "MoodUI",
+    "AdaptiveEngine",
+    "AdaptiveConfig",
+    "InteractionSignal",
+    "InteractionState",
+    "StateTransition",
+    "STATUS",
+]