Metadata-Version: 2.4
Name: minxg-beta
Version: 0.20.1
Summary: minxg-beta — modular AI worker platform with a chat CLI, an OpenAI-compatible v1 gateway, opt-in extensions (ADB/ROOT/files), and a self-developed temporal driver engine. 376 operators in 11 categories (306 of them mathematical across 6 pillars). Pure Python. Published on PyPI as `minxg-beta` — `pip install minxg-beta`.
Author: MINXG Authors
License: MIT
Project-URL: Homepage, https://github.com/pineapple-ooo/MINXG-beta
Project-URL: Documentation, https://github.com/pineapple-ooo/MINXG-beta/blob/main/README.md
Project-URL: Repository, https://github.com/pineapple-ooo/MINXG-beta
Project-URL: Issues, https://github.com/pineapple-ooo/MINXG-beta/issues
Project-URL: Changelog, https://github.com/pineapple-ooo/MINXG-beta/blob/main/CHANGELOG.md
Keywords: ai,orchestration,workers,operator,driver,self-evolution,lossless,polyglot,minxg
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: PyYAML>=6.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: prometheus-client>=0.20.0
Requires-Dist: ujson>=5.9.0
Requires-Dist: zstandard>=0.22.0
Requires-Dist: xxhash>=3.4.0
Requires-Dist: orjson>=3.9.0
Requires-Dist: fastapi<1,>=0.104.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: uvicorn[standard]<1,>=0.24.0
Requires-Dist: rich>=13.0.0
Requires-Dist: readchar>=2.0.0
Requires-Dist: httpx[socks]>=0.27.0
Requires-Dist: croniter>=6.0.0
Requires-Dist: prompt_toolkit>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=9.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.4.0; extra == "dev"
Requires-Dist: ruff>=0.16.0; extra == "dev"
Dynamic: license-file

# MINXG-beta — AI CLI and API Gateway

**Version:** v0.20.1  
**Status:** ⚠️ UNSTABLE — This build is undergoing major architectural refactoring.
The CLI (CLI chat) has been rewired as the default entry point with the agent
orchestrator permanently merged into normal conversation. The CLI now uses a
minimal hybridism design (conditional env bar, two-tier palette, streaming-first).
The Web UI is still accessible via `minxg web`.

This update isn't like the usual slow drip updates — feel free to use it 🗿

---

## What is MINXG-beta?

MINXG-beta is a Python-based AI CLI and API gateway. In plain terms it gives you:

- A **chat CLI** with streaming, tool calling, and multi-provider model support
- An **OpenAI-compatible `/v1` API gateway**, including MCP server mode
- A **worker system** (file, network, crypto, math, text, system, AI) that the agent can call
- A **math/science operator layer** (geometric algebra, category theory, information geometry, topology, chaos, fiber bundles, symbolic differential algebra) — a niche strength, not a general-purpose math library
- **Optional bridges** to C/C++, Rust, Go, Java, Julia, R, WebAssembly, and Datalog (most are not built by default)
- **Optional multi-channel** relays for Telegram, Discord, Slack (off by default, outbound only)
- A **markdown skill system** (instruction packs, no code execution on install)
- A **multi-agent collaboration layer** for planning and parallel execution
- **Self-evolution** and **reverse engineering** tooling, scoped to academic/interop use

This is a single-developer, actively-refactored project. Read the [Known Limitations](#known-limitations) section before treating it as production infrastructure.

### Recent maintenance notes

- ⚠️ **This build is transitional.** The CLI (prompt_toolkit-based chat) is now
  the default entry point (`minxg` without arguments). The agent orchestrator
  (`NexusOrchestrator`) is permanently merged into conversation — there is no
  toggle to disable it because without it the system cannot converse.
- **CLI (Chat CLI):** 3-layer hybridism design — conditional env bar (only during thinking/tool/progress), flexible output window, single-line `>` input. Two-tier palette: white/light-blue for `◆` and `>` prefixes, red for errors, dark gray for tool output. Streaming-first, character-by-character.
- **Known issues:** API 401 errors may still occur with misconfigured providers.
  The Web UI (`minxg web`) remains functional.
- The `minxg` command no longer starts the Web UI by default — use `minxg web`
  explicitly for the browser interface.
- CLI history and compatibility tests now include a small fallback for legacy
  Android path checks.

---


## Honest Comparison

| Capability | MINXG-beta | Notes |
|------------|-------|-------|
| Tool breadth | 63 workers across 7 categories | Real count, not inflated; more planned |
| MCP server | ✅ Yes | Exposes all workers as MCP tools |
| OpenAI-compatible API | ✅ Yes | `/v1/chat/completions`, streaming |
| Mathematical operators | 200+ operators across 7 pillars | Niche strength; not general-purpose |
| Polyglot bridges | 8 runtimes | C/C++, Rust, Go, Java, Julia, R, WASM, Datalog |
| Multi-channel (Telegram/Discord/Slack) | Opt-in | Long-polling / websocket, no public port |
| Agent framework | Built-in multi-agent orchestration | Commander/session/reviewer flow; functional but still evolving |
| RAG system | Vector + hybrid search | Basic implementation |
| Workflow engine | DAG with branching/loops | Early stage |
| Guardrails | Input/output validation, PII, toxicity, prompt injection, hallucination, code injection prevention | Comprehensive regex-based screening |
| Desktop OS support (Windows/macOS/Linux) | Not tested on real hardware | CI mocks only; report issues if you hit them |

We are **not** "better than everyone." We have genuine depth in math/science operators and polyglot bridges, but we lag on messaging-platform reach, community skill breadth, and production hardening compared to established projects like OpenClaw or LangChain. If you need a wide messaging ecosystem or a mature plugin marketplace, those are better choices today.

---

## Honest Development Notes

This is a **single-developer project**. Most code has been written or refactored with the help of AI assistants — which is not unusual in this space, but worth stating plainly.

**Platform testing is limited to what the developer can run locally.** Windows, macOS, and general Linux desktop code paths have **not** been tested on real hardware. If the software claims to work on those platforms but breaks, that's a real gap — not your fault. Please report issues so we can close them.

We are transparent about this limitation rather than pretending full cross-platform support that doesn't exist.

---

## Quick Start

```bash
pip install minxg-beta

# Verify installation
minxg doctor
```

Run `minxg` with no arguments to start the chat CLI. Use `minxg gateway --mcp` for the MCP server.

---

## Core Features

### Chat CLI (`minxg`)
- Streaming responses with tool-call visualization
- 32+ model providers (OpenAI, Anthropic, Google, DeepSeek, xAI, local via Ollama, etc.)
- Mid-conversation model switching (`/model`)
- Multi-language UI (12 languages, live-switchable with `/lang`)
- Theme system (8 built-in themes)

### API Gateway (`minxg gateway`)
- OpenAI-compatible `/v1/chat/completions` endpoint
- MCP server mode: `minxg gateway --mcp`
- All 63 workers exposed as callable tools
- Cost tracking, rate limiting, request logging

### Built-in Multi-Agent Collaboration (Always-On)

The agent orchestrator is permanently merged into the normal conversation flow.
When you type a message in the CLI, it's routed through the `NexusOrchestrator`
which provides:

- **Tool-calling loop** with iteration budget, anti-loop guards, and dedup cache
- **Streaming response** with real-time token, thinking, and tool-call events
- **Infinite context** via layered memory (working + episodic + semantic)
- **Session persistence** across restarts via SQLite-backed session store
- **Multi-agent routing** (commander / session / reviewer / shared task board)
  for planning, parallel execution, and conflict-aware handoff
- **No toggle to disable** — the agent IS the conversation layer. Turning it off
  would make the system incapable of conversing.

Formerly a separate "Nexus" / `company_mode` feature, the agent orchestration is
now the foundation of every chat session. Run `minxg` to start. Type `/help` for
available slash commands.

### Worker System
63 worker classes organized in 7 categories (all implemented and tested):
- **I/O**: file (9 workers), network (9 workers)
- **Crypto**: 9 workers (AES, hashing, HMAC, PBKDF2, signing, key generation)
- **Math**: 8 workers (calculator, stats, linear algebra, calculus, Fourier, primes, geometry, number theory)
- **System**: 10 workers (info, process, disk, memory, CPU, network, env, uptime, fd)
- **Text**: 9 workers (process, summarize, translate, sentiment, keywords, entities, regex, diff, plagiarism)
- **AI**: 9 workers (chat, embeddings, classify, extract, OCR, STT, TTS, summarize, QA)
- **Registry**: 1 central registry with auto-discovery

WIP/planned: image, audio, video, PDF, archive, cloud, database workers.

### Mathematical Pillars (7 + Geometry)
- **Geometric Algebra** — multivector calculus
- **Category Theory** — functors, monads, morphisms
- **Information Geometry** — Fisher metric, natural gradient
- **Topology** — homology, cohomology, spectral sequences
- **Chaos Theory** — Lyapunov exponents, bifurcation, fractals
- **Fiber Bundles** — connections, curvature, parallel transport
- **Symbolic Differential Algebra** — jets, Lie brackets, differential ideals
- **GeometryWorker** — driver-geometry integration layer

### Polyglot Bridges (8 runtimes)
| Runtime | Bridge | Notes |
|---------|--------|-------|
| C/C++ | `c_core/`, `cpp_core/` | FFI via cffi / pybind11 |
| Rust | `rust_core/` | `minxg_rust_core` crate, ctypes |
| Go | `go_core/` | JSON-RPC over stdio |
| Java | `java_core/` | JVM daemon + vector engine |
| Julia | `julia_worker.py` | `minxg.contracts.runtime.julia` |
| R | `r_worker.py` + `r_scripts/` | Statistical computing |
| WASM | `wasm_worker.py` | Wasmtime sandbox |
| Datalog | `datalog_worker.py` | Clingo / pyDatalog |

### Skill System (`minxg skill ...`)
- Markdown `SKILL.md` files with YAML frontmatter
- Local or remote catalogs (JSON file, raw GitHub URL works)
- `minxg skill search / install / new / publish`
- Also exposed to the chat agent as `skill_search`, `skill_install`, `skill_new` tools
- **No code execution on install** — skills are instruction packs, not plugins

### Multi-Channel Gateway
- Telegram (long-polling), Discord (websocket), Slack (websocket)
- Disabled by default; enable in `config/gateway.yaml`
- No public port required — all outbound
- See `gateway/channel_*.py` for per-channel status and known gaps

---

## CLI Reference

```bash
minxg                    # Start chat CLI (default)
minxg setup              # Run setup wizard
minxg config             # Show current configuration
minxg status             # Runtime status
minxg tools              # List available tools
minxg model [name]       # Set or view model
minxg api <url>          # Quick-set API base URL
minxg key <key>          # Quick-set API key
minxg lang [code]        # Switch display language
minxg gateway [--detach] # API gateway (foreground default)
minxg gateway --mcp      # MCP server mode
minxg doctor             # Self-check (config + tools + extensions)
minxg ext <sub>          # Extension management
minxg skill <sub>        # Skill management
minxg features           # Feature showcase
minxg themes             # Theme management
minxg export             # Export memories (json/markdown)
minxg import <file>      # Import memories
minxg help               # Show this cheatsheet
```

---

## MCP Server Setup

### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "minxg": {
      "command": "minxg",
      "args": ["gateway", "--mcp"]
    }
  }
}
```

### Cursor / Windsurf / Any MCP Client
Same configuration; the `--mcp` flag exposes all workers as MCP tools.

---

## Platform Notes

### Desktop platforms (Windows / macOS / Linux)
Code paths for these platforms exist and are covered by mocked-path CI tests, but have **not been verified on real hardware**. If you run MINXG-beta on a desktop OS and something breaks, that's a known gap — please report it.

---

## Contributing

1. Fork the repository
2. Read `docs/ARCHITECTURE_quickstart.md` for the module layout rationale
3. For deeper architecture background, see `docs/ARCHITECTURE.md`
4. Make your changes
5. Run `pytest tests/` — all tests must pass
6. Submit a PR

See `docs/CONTRIBUTING.md` for details.

---

## License

MIT. Use freely. We take no responsibility for what your AI does.

---

## Known Limitations

- **Unstable, transitional build.** The architecture is being refactored actively.
  Internal interfaces can change between releases without backward compatibility.
- **Agent orchestration is always on.** There is no bare-chat mode. The
  `NexusOrchestrator` is the conversation layer; turning it off breaks the CLI.
  This adds latency and API calls compared with a plain chat client.
- **Not hardened for production.** The gateway, session store, and guardrails
  are functional but have not had security review, load testing, or abuse
  testing. Do not expose the gateway to the public internet without a reverse
  proxy, authentication, and rate limiting you manage yourself.
- **Guardrails are regex/heuristic-based.** They catch obvious injection and
  PII patterns, but they are not a reliable safety layer. Do not depend on
  them for compliance, content moderation, or security.
- **Multi-channel relays are best-effort.** Telegram/Discord/Slack support is
  outbound-only and not feature-complete. Message ordering, retries, and
  reconnection behavior are not guaranteed.
- **Polyglot bridges are optional and uneven.** C/C++, Go, Java, and several
  others are documented as bridges but are not built or tested by default.
  Only the Python-native workers are reliably available out of the box.
- **Desktop OS platforms are untested on real hardware.** Windows, macOS, and
  general Linux desktop code paths are covered by mocked-path CI tests only;
  expect networking and command-execution quirks.
- **Math/science operators are a specialty, not a general math engine.** The
  seven pillars are implemented, but edge cases and numerical robustness are
  not guaranteed the way a dedicated library (NumPy, SymPy, etc.) would be.
- **Single-developer maintenance.** Response times to issues and the pace of
  breaking changes are not predictable.

## Use With Caution

- Run `minxg doctor` before relying on any feature; it reports missing
  dependencies and degraded capabilities for your platform.
- Keep API keys in `config.yaml` / environment, never in command history.
- Back up the session store before upgrades — schema can change between builds.
- Prefer the chat CLI and the local gateway over the multi-channel relays
  until you have tested the relay you intend to use end to end.
- Treat self-evolution and reverse-engineering tooling as academic/interop
  features, not as audited security or safety tools.

## Good For / Not For

| If you need... | MINXG-beta | Consider instead |
|---|---|---|
| A local, extensible AI CLI with math/science operators | Reasonable fit | — |
| An OpenAI-compatible gateway you run yourself | Reasonable fit (self-hosted) | — |
| Public internet exposure / high availability | Not suitable | Managed API / reviewed gateway |
| Reliable content moderation or compliance guardrails | Not suitable | Dedicated safety service |
| Mature plugin marketplace / messaging ecosystem | Not suitable | Established platforms |
| Production security guarantees | Not suitable | Audited, reviewed software |

---

## 👋 Got Questions?

Little babe still wants my contact info 🤫 no way 🗿

Try `minxg help`, stare at `docs/ARCHITECTURE.md` until it starts making sense, or just `minxg doctor` and let the machine tell you what's broken. If that fails, file an issue and hope I notice it between refactor binges. Otherwise... you know what, just `grep` the source yourself, it's all there. 🗿

---

*Version v0.20.1 — transitional build. Read the limitations before deploying.*
