Skip to content

Commit fe5e5d2

Browse files
1minds3t1minds3t
authored
Update README.md
1 parent abcca53 commit fe5e5d2

1 file changed

Lines changed: 96 additions & 121 deletions

File tree

‎README.md‎

Lines changed: 96 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -1,135 +1,110 @@
11
# omnipkg: The Intelligent Python Package Manager
2-
One environment. Infinite versions. Zero conflicts.
2+
> One environment. Infinite versions. Zero conflicts.
3+
34
<p align="center">
4-
<a href="https://github.com/1minds3t/omnipkg/actions/workflows/test.yml">
5-
<img src="https://img.shields.io/github/actions/workflow/status/1minds3t/omnipkg/test.yml?branch=main" alt="Build Status">
6-
</a>
7-
<a href="https://pypi.org/project/omnipkg/">
8-
<img src="https://img.shields.io/pypi/v/omnipkg.svg" alt="PyPI version">
9-
</a>
10-
<a href="https://www.gnu.org/licenses/agpl-3.0">
11-
<img src="https://img.shields.io/badge/License-AGPLv3-red.svg" alt="License: AGPLv3">
12-
</a>
13-
<a href="https://github.com/1minds3t/omnipkg/actions/workflows/security_audit.yml">
14-
<img src="https://img.shields.io/github/actions/workflow/status/1minds3t/omnipkg/security_audit.yml?branch=main" alt="Security Audit">
15-
</a>
5+
<a href="https://github.com/1minds3t/omnipkg/actions/workflows/test.yml">
6+
<img src="https://img.shields.io/github/actions/workflow/status/1minds3t/omnipkg/test.yml?branch=main" alt="Build Status">
7+
</a>
8+
<a href="https://pypi.org/project/omnipkg/">
9+
<img src="https://img.shields.io/pypi/v/omnipkg.svg" alt="PyPI version">
10+
</a>
11+
<a href="https://www.gnu.org/licenses/agpl-3.0">
12+
<img src="https://img.shields.io/badge/License-AGPLv3-red.svg" alt="License: AGPLv3">
13+
</a>
14+
<a href="https://github.com/1minds3t/omnipkg/actions/workflows/security_audit.yml">
15+
<img src="https://img.shields.io/github/actions/workflow/status/1minds3t/omnipkg/security_audit.yml?branch=main" alt="Security Audit">
16+
</a>
1617
</p>
17-
omnipkg lets you install any version of any package without breaking your environment, downgrading dependencies, or needing Conda, Docker, or pipx. Dependency hell? Obliterated.
1818

19-
Installation & The 30-Second Demo
20-
Get started in seconds. After installing, run the interactive demo to see the magic for yourself.
19+
---
20+
21+
`omnipkg` lets you install *any version* of *any package* without breaking your environment, downgrading dependencies, or needing Conda, Docker, or `pipx`. **Dependency hell? Obliterated.**
2122

22-
Generated bash
23+
## Installation & Quick Start
24+
25+
```bash
2326
pip install omnipkg
27+
```
28+
29+
See the magic for yourself. This command runs a fully automated demo showcasing downgrade protection and version isolation.
30+
31+
```bash
2432
omnipkg demo
33+
```
2534

26-
content_copy
35+
## 🔥 See It to Believe It (Live Demo Recording)
2736

28-
download
29-
Use code with caution.
30-
Bash
31-
The demo will guide you through a real-world dependency conflict, showcasing how omnipkg isolates the problem version instead of breaking your environment.
37+
A static README can't do it justice. Here is a live recording of `omnipkg` handling a complex installation that would break other tools.
3238

33-
<details>
34-
<summary><strong>🔬 Click to see what the demo shows you</strong></summary>
35-
Generated bash
36-
# The demo first shows you what happens when you use pip...
37-
💀 You: pip install flask-login==0.4.1
38-
...
39-
💥 BOOM! Look what pip did:
40-
❌ Uninstalled flask-login 0.6.3
41-
❌ Downgraded Flask and Werkzeug
42-
❌ Your modern project is now BROKEN
43-
44-
# Then, it shows you the omnipkg way...
45-
🧠 Smart choice! Using omnipkg instead...
46-
🫧 Creating a protective bubble for the old version...
47-
$ omnipkg install flask-login==0.4.1
48-
✅ omnipkg install successful!
49-
🎯 BOTH versions now coexist peacefully!
50-
51-
content_copy
52-
53-
download
54-
Use code with caution.
55-
Bash
56-
</details>
57-
🔥 The Gauntlet: Surviving the Stress Test
58-
Talk is cheap. Here’s what happens when omnipkg is pushed to its absolute limit with the built-in omnipkg stress-test command. This isn't a simulation; it's omnipkg seamlessly activating different, often incompatible, versions of C-extension-heavy libraries in the same Python process.
39+
*<-- This is the perfect spot for a GIF created with a tool like `asciinema` or `termtosvg`! -->*
40+
41+
![omnipkg Demo GIF](https://user-images.githubusercontent.com/your-image-url-here.gif)
42+
*This shows `omnipkg install old-package`, downgrade protection activating, and `omnipkg status` confirming both versions coexist.*
43+
44+
---
45+
46+
## 🚀 Core Features
47+
48+
- 🛡️ **Downgrade Protection**: Stops `pip` from nuking your environment by isolating conflicting versions into protected **"bubbles."**
49+
- 💾 **Intelligent Deduplication**: Saves up to 60% disk space on bubbled packages while keeping native C extensions stable and separate.
50+
- 🧠 **Redis-Backed Knowledge Base**: Lightning-fast lookups for all package versions, dependencies, and security info.
51+
- 🔀 **Runtime Version Switching**: Activate any bubbled package version on the fly, even within the same script, using the built-in loader.
52+
- 🧪 **Battle-Tested**: Proven to handle massive environments (**520+ packages, 95+ bubbles, 15.4GB+**) without flinching.
53+
54+
---
55+
56+
## How Is This Possible?
57+
58+
When a downgrade is detected, `omnipkg` performs surgery:
59+
1. **Intercepts** the request.
60+
2. **Installs** the conflicting version and its entire dependency tree into a temporary, isolated location.
61+
3. **Creates** a space-efficient, deduplicated "bubble" in `.omnipkg_versions`.
62+
4. **Restores** the original package in your main environment, leaving it pristine.
63+
64+
The result: a perfectly stable global environment, with every version you've ever needed on standby.
5965

6066
<details>
61-
<summary><strong>🤯 Click to view the full stress test output.</strong></summary>
62-
Generated bash
63-
# Creating bubbles for older, conflicting versions...
64-
--- Creating bubble for numpy==1.24.3 ---
65-
✅ Bubble created: 1363 files copied, 0 deduplicated.
66-
--- Creating bubble for scipy==1.12.0 ---
67-
✅ Bubble created: 3551 files copied, 0 deduplicated.
68-
69-
# Executing the test...
70-
💥 NUMPY VERSION JUGGLING:
71-
72-
⚡ Switching to numpy==1.24.3
73-
🌀 omnipkg loader: Activating numpy==1.24.3...
74-
✅ Activated bubble: /path/to/.omnipkg_versions/numpy-1.24.3
75-
✅ Version: 1.24.3
76-
🔢 Array sum: 6
77-
78-
⚡ Switching to numpy==1.26.4
79-
🌀 omnipkg loader: Activating numpy==1.26.4...
80-
🧹 Deactivated bubble: numpy-1.24.3
81-
✅ Activated bubble: /path/to/.omnipkg_versions/numpy-1.26.4
82-
✅ Version: 1.26.4
83-
🔢 Array sum: 6
84-
85-
🔥 SCIPY C-EXTENSION TEST:
86-
87-
🌋 Switching to scipy==1.12.0
88-
🌀 omnipkg loader: Activating scipy==1.12.0...
89-
✅ Activated bubble: /path/to/.omnipkg_versions/scipy-1.12.0
90-
✅ Version: 1.12.0
91-
♻️ Sparse matrix: 3 non-zeros
92-
93-
🌋 Switching to scipy==1.16.1
94-
🌀 omnipkg loader: Activating scipy==1.16.1...
95-
🧹 Deactivated bubble: scipy-1.12.0
96-
✅ System version already matches requested version (1.16.1). No bubble activation needed.
97-
✅ Version: 1.16.1
98-
♻️ Sparse matrix: 3 non-zeros
99-
100-
🚨 OMNIPKG SURVIVED NUCLEAR TESTING! 🎇
101-
102-
content_copy
103-
104-
download
105-
Use code with caution.
106-
Bash
67+
<summary><strong>🔬 Real-World Example: Downgrading PyTorch</strong></summary>
68+
69+
```bash
70+
# User wants to install an older torch version
71+
$ omnipkg install torch==2.7.0
72+
73+
# ... (omnipkg detects the downgrade) ...
74+
🛡️ DOWNGRADE PROTECTION ACTIVATED!
75+
-> Fixing downgrade: torch from v2.7.1 to v2.7.0
76+
🫧 Creating isolated bubble for torch v2.7.0
77+
✅ Success: Dependencies resolved via PyPI API.
78+
🧹 Creating deduplicated bubble...
79+
⚠️ Disabling deduplication for native package: torch
80+
✅ Bubble created: 16241 files copied, 3211 deduplicated.
81+
📊 Space efficiency: 16.5% saved.
82+
🔄 Restoring ‘torch’ to safe version v2.7.1 in main environment…
83+
84+
✅ Environment protection complete!
85+
```
10786
</details>
108-
🚀 Core Features
109-
🛡️ Downgrade Protection: Stops pip from nuking your environment by isolating conflicting versions into protected "bubbles."
110-
💾 Intelligent Deduplication: Saves up to 60% disk space on bubbled packages while keeping native C extensions stable and separate.
111-
🧠 Redis-Backed Knowledge Base: Lightning-fast lookups for all package versions, dependencies, and security info.
112-
🔀 Runtime Version Switching: Activate any bubbled package version on the fly, even within the same script, using the built-in loader.
113-
🧪 Battle-Tested: Proven to handle massive environments (520+ packages, 95+ bubbles, 15.4GB+) without flinching.
114-
How It Works
115-
When a downgrade is detected, omnipkg performs surgery:
116-
117-
Intercepts the request.
118-
Installs the conflicting version and its entire dependency tree into a temporary location.
119-
Creates a space-efficient, deduplicated "bubble" in .omnipkg_versions.
120-
Restores the original package in your main environment, leaving it pristine.
121-
The result: a perfectly stable global environment, with every version you've ever needed on standby.
12287

123-
Why Other Tools Fail
124-
Tool The Task: install old-conflicting-package Result
125-
pip ❌ ERROR: Cannot uninstall...
126-
conda ⏳ Solving environment... (for hours)
127-
poetry 💥 SolverProblemError
128-
uv 🚫 No solution found for the request
129-
omnipkg ✅ DOWNGRADE PROTECTION ACTIVATED!
130-
📜 Licensing
131-
omnipkg is available under a dual-license model.
132-
133-
Community Edition (AGPLv3): Perfect for individual developers, open-source projects, and academic use. If you use omnipkg in a project that is also open-source under a compatible license, you're good to go.
134-
Commercial License: Required for use in closed-source commercial software or for any organization that cannot comply with the AGPLv3. This license allows you to integrate omnipkg without the obligation to open-source your own code.
135-
→ To inquire about a commercial license, please contact: omnipkg@proton.me
88+
---
89+
90+
## Why Other Tools Fail
91+
92+
| Tool | The Task: `install old-conflicting-package` | Result |
93+
|---------------|---------------------------------------------|---------------------------------------|
94+
| `pip` | ❌ | `ERROR: Cannot uninstall...` |
95+
| `conda` | ⏳ | `Solving environment...` (for hours) |
96+
| `poetry` | 💥 | `SolverProblemError` |
97+
| `uv` | 🚫 | `No solution found for the request` |
98+
| **`omnipkg`** | ✅ | **`DOWNGRADE PROTECTION ACTIVATED!`** |
99+
100+
---
101+
102+
## 📜 Licensing
103+
104+
`omnipkg` is available under a dual-license model to suit different needs.
105+
106+
- **Community Edition (AGPLv3):** Perfect for individual developers, open-source projects, and academic use. If you use `omnipkg` in a project that is also open-source under a compatible license, you're good to go. The source code is available in this repository under the [GNU AGPLv3](LICENSE).
107+
108+
- **Commercial License:** Required for use in closed-source commercial software, proprietary systems, or for any organization that cannot comply with the terms of the AGPLv3. This license allows you to integrate `omnipkg` without the obligation to open-source your own code.
109+
110+
→ **To inquire about a commercial license, please contact:** [**omnipkg@proton.me**](mailto:omnipkg@proton.me)

0 commit comments

Comments
 (0)