Metadata-Version: 2.4
Name: ghostchimera
Version: 0.4.0b1
Summary: Local-first agent orchestration prototype with Chimera Pilot scheduling and runtime control.
Author: Ghost Chimera Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/fernandogarzaaa/GHOST-Chimera
Project-URL: Repository, https://github.com/fernandogarzaaa/GHOST-Chimera
Project-URL: Issues, https://github.com/fernandogarzaaa/GHOST-Chimera/issues
Project-URL: Documentation, https://github.com/fernandogarzaaa/GHOST-Chimera/blob/main/docs/quick-start.md
Project-URL: Changelog, https://github.com/fernandogarzaaa/GHOST-Chimera/blob/main/CHANGELOG.md
Keywords: agents,orchestration,local-first,runtime,scheduler
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: certifi>=2024.2.2
Requires-Dist: croniter>=6.0.0
Requires-Dist: cryptography>=42.0
Requires-Dist: jsonschema>=4.0
Requires-Dist: websockets<18,>=12.0
Provides-Extra: desktop
Requires-Dist: pyautogui>=0.9.54; extra == "desktop"
Provides-Extra: quantum
Requires-Dist: pyqpanda3>=0.3.5; extra == "quantum"
Provides-Extra: local
Requires-Dist: llama-cpp-python>=0.3.0; extra == "local"
Provides-Extra: minimind
Requires-Dist: torch>=2.6; python_version < "3.14" and extra == "minimind"
Requires-Dist: transformers>=4.57.0; python_version < "3.14" and extra == "minimind"
Requires-Dist: tokenizers>=0.20.0; python_version < "3.14" and extra == "minimind"
Provides-Extra: cute
Requires-Dist: nvidia-cutlass-dsl>=4.0; (python_version == "3.12" and platform_system == "Linux") and extra == "cute"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: gateway
Requires-Dist: websockets<18,>=12.0; extra == "gateway"
Requires-Dist: croniter>=6.0.0; extra == "gateway"
Provides-Extra: voice
Requires-Dist: SpeechRecognition>=3.10; extra == "voice"
Requires-Dist: faster-whisper>=1.0; extra == "voice"
Requires-Dist: pocketsphinx>=5.0; extra == "voice"
Requires-Dist: vosk>=0.3.45; extra == "voice"
Requires-Dist: av>=10.0; extra == "voice"
Requires-Dist: edge-tts>=6.0; extra == "voice"
Provides-Extra: all
Requires-Dist: certifi>=2024.2.2; extra == "all"
Requires-Dist: croniter>=6.0.0; extra == "all"
Requires-Dist: cryptography>=42.0; extra == "all"
Requires-Dist: jsonschema>=4.0; extra == "all"
Requires-Dist: pyautogui>=0.9.54; extra == "all"
Requires-Dist: websockets<18,>=12.0; extra == "all"
Requires-Dist: fsspec[http]<=2026.9.0,>=2023.1.0; extra == "all"
Requires-Dist: pyqpanda3>=0.3.5; extra == "all"
Requires-Dist: llama-cpp-python>=0.3.0; extra == "all"
Requires-Dist: torch>=2.6; python_version < "3.14" and extra == "all"
Requires-Dist: transformers>=4.57.0; python_version < "3.14" and extra == "all"
Requires-Dist: tokenizers>=0.20.0; python_version < "3.14" and extra == "all"
Requires-Dist: nvidia-cutlass-dsl>=4.0; (python_version == "3.12" and platform_system == "Linux") and extra == "all"
Requires-Dist: mcp>=1.0.0; extra == "all"
Requires-Dist: SpeechRecognition>=3.10; extra == "all"
Requires-Dist: faster-whisper>=1.0; extra == "all"
Requires-Dist: pocketsphinx>=5.0; extra == "all"
Requires-Dist: vosk>=0.3.45; extra == "all"
Requires-Dist: av>=10.0; extra == "all"
Requires-Dist: edge-tts>=6.0; extra == "all"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: pillow>=10.0; extra == "dev"
Dynamic: license-file

﻿# Ghost Chimera

![Version](https://img.shields.io/badge/version-0.4.0--beta-blueviolet)
![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![CI](https://img.shields.io/badge/CI-ubuntu%20%7C%20windows%20%7C%20macos-brightgreen)

> **Ghost is background AI infrastructure.** Ghost Chimera observes events across your digital workflow, learns how you work, and quietly prepares the right context or action for whichever AI agent you're using — without fine-tuning or replacing the underlying model. Your AI agents do the thinking. Ghost remembers what matters and makes sure they know what they need.

Ghost Chimera is a **local-first ambient intelligence runtime** built around the **Stealth Loop** — an event-driven learning and intervention cycle (`ghostchimera/stealth/`): EVENT → UNDERSTAND → UPDATE STATE → RECALL EXPERIENCE → MATCH WORKFLOW → PREDICT → DECIDE → PREPARE / INJECT / ACT → OBSERVE OUTCOME → LEARN. **Chimera Pilot** remains as the execution capability underneath it: it compiles natural-language objectives into steps, runs them across registered backends with safety policy and fallbacks, and records telemetry.

This is beta-stage software for real, user-supervised work in local-first environments. It is not AGI, not a secure sandbox for untrusted code by itself, and not a replacement for licensed quantum operating systems.

## Install

```bash
pip install ghostchimera            # Python: headless core, installs in seconds
pip install "ghostchimera[all]"     # Python: every backend (slow, see note below)
brew tap fernandogarzaaa/ghostchimera && brew install --HEAD ghostchimera
```

> **Install time:** the `[all]` extra pulls every backend (desktop, local models, MCP, voice, quantum),
> including large ML and native packages (torch, transformers, llama-cpp-python, the voice stack).
> It can take well over 10 minutes on a typical connection. New users should start with the base
> package and add only the extras they need, for example `pip install "ghostchimera[mcp,gateway]"`.

Full matrix (extras, publishing): [docs/INSTALL.md](docs/INSTALL.md)

## One-Line Install

The one-line path creates a local checkout, builds a virtual environment, installs the full Ghost Chimera runtime profile, verifies the CLI, and prints the launch command.

**Windows PowerShell:**

```powershell
irm https://raw.githubusercontent.com/fernandogarzaaa/GHOST-Chimera/main/scripts/install.ps1 | iex
```

**macOS / Linux:**

```bash
curl -fsSL https://raw.githubusercontent.com/fernandogarzaaa/GHOST-Chimera/main/scripts/install.sh | bash
```

Then launch (`scripts/install.ps1` on Windows, `scripts/install.sh` on macOS/Linux):

```bash
cd ~/ghost-chimera
.venv/bin/ghostchimera console
```

Installer options are environment variables. `GHOSTCHIMERA_EXTRAS` defaults to the full Ghost Chimera runtime plus verification tools; override it only for constrained development installs.

## Runtime Specs

**Minimum for Ghost Console and local orchestration:**

| Component | Minimum | Recommended |
|---|---|---|
| OS | Windows 10/11, macOS 13+, Ubuntu 22.04+ | Windows 11, macOS 14+, Ubuntu 24.04+ |
| Python | 3.11 | 3.12 or 3.13 |
| RAM | 4 GB | 8-16 GB |
| Disk | 2 GB free | 10+ GB for memory, traces, and local models |
| Browser | Current Chrome, Edge, Firefox, or Safari | Current Chrome or Edge |

The full install covers Python package dependencies — not model weights, API keys, GPU drivers, or build tools. Without provider credentials, Ghost still runs the console, memory tools, trust runtime, evals, and deterministic backends.

## Usage in 5 minutes (no terminal needed)

Ghost Console is the point-and-click dashboard for everyday use:

1. Start Ghost (`ghostchimera console` or Docker) and open `http://localhost:8766/`.
2. The Setup wizard helps you pick an AI provider — choose **OpenCode CLI** or **Local** to start free.
3. In **Operate → Run**, type an objective in plain words ("Summarize my inbox priorities") and press run.
4. Check **Operate → Memory** for what Ghost remembered and **Advanced → Trust** for the run journal with replay.
5. Type `/ghost status` inside Claude Code, OpenCode, Codex, or Gemini CLI to see Ghost working there too.

Full walkthrough with use cases, everyday recipes, and the safety model: **[docs/USAGE_GUIDE.md](docs/USAGE_GUIDE.md)**. Guided first run: [docs/USER_TUTORIAL.md](docs/USER_TUTORIAL.md).

## What it can do for you

- **Personal productivity** — morning briefings, meeting prep, inbox triage drafts (never auto-sent), and asking your own history questions.
- **Operator workflows** — repeatable VA-style runs with approval checkpoints, reusable Standing Orders, and phone control from messaging apps.
- **Developer leverage** — project context auto-injected into your coding agents, free/local model options, and approval-gated computer use (browser and desktop).

## How it works

1. **The Stealth Loop watches and learns.** Events flow through understand → recall → predict → decide. Silence is the default; most events produce nothing visible.
2. **Chimera Pilot does.** Approved objectives compile into steps across deterministic, local-model, browser, and desktop backends — dry-runnable before anything touches the world.
3. **Trust Runtime keeps receipts.** Every run, approval, and outcome is journaled locally and replayable.

## Cloud reasoning: NVIDIA Nemotron on Nebius Token Factory

Ghost stays local-first by default, but the Stealth Loop can consult NVIDIA's
open Nemotron models in the cloud when you want deeper understanding than the
deterministic engines provide.

**Where Token Factory accelerates the workflow** — the optional
`NemotronReasoner` (`ghostchimera/stealth/nemotron_reasoning.py`) plugs into
the Stealth Loop's UNDERSTAND and PREDICT phases:

- **UNDERSTAND** — Nemotron 3 Nano (`nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B`) interprets
  an observation and returns a structured read (intent, confidence, suggested
  workflow, risk flags). Fast and cheap, so it can run per high-value event.
- **PREDICT** — Nemotron 3 Super (`nvidia/nemotron-3-super-120b-a12b`) sharpens
  next-action predictions with real reasoning when the loop needs it.
- Insights land in the loop's trace (`trace["nemotron"]`) and in intervention
  provenance. Anything classified `secret` is never sent to the cloud, and a
  failed cloud call degrades silently to the local loop.

**Setup** — get a key at <https://console.nebius.com> (Token Factory → API
keys; free credits via the Nebius Builder Program), then:

```bash
export NEBIUS_API_KEY="..."
export NEBIUS_MODEL="nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B"   # optional override
```

Or pick **Nebius Token Factory** in the setup wizard / model picker
(`NEBIUS_API_KEY` + `NEBIUS_MODEL` are the env vars). Attach the reasoner
programmatically:

```python
from ghostchimera.stealth import StealthLoop, build_cloud_enhancements

reasoner, grounding = build_cloud_enhancements()  # (None, None) without keys
loop = StealthLoop(reasoner=reasoner, grounding=grounding)
```

**Web grounding with Tavily** — when an event asks for fresh facts
(`payload["ground_with_web"]` or a research/news-style event), the UNDERSTAND
phase grounds it through Tavily, MCP-first:

1. Remote Tavily MCP server (`https://mcp.tavily.com/mcp`, `tavily-search` /
   `tavily-extract`) via the stdlib MCP client in `ghostchimera/mcp/mcp_protocol.py`
2. Local `tavily-mcp` over stdio (`npx -y tavily-mcp`)
3. Direct REST fallback (`POST https://api.tavily.com/search`)

```bash
export TAVILY_API_KEY="..."   # get one at https://tavily.com
# optional: TAVILY_MCP_MODE=auto|remote|local|rest (default: auto)
```

**Observability (optional)** — Nebius chat completions and Tavily
search/extract calls can be traced to [LangSmith](https://smith.langchain.com)
with zero new dependencies (a stdlib-only client posts to the LangSmith
ingest API; the SDK is not required and not installed). Tracing is strictly
opt-in: with no `LANGSMITH_API_KEY` set, nothing changes.

```bash
export LANGSMITH_API_KEY="..."          # from https://smith.langchain.com
export LANGSMITH_PROJECT="ghost-chimera-hackathon"  # optional, this is the default
export LANGSMITH_TRACING=1              # set to 0 to disable while keeping the key
```

Traced runs show up as `nebius.chat_completion`, `tavily.search`, and
`tavily.extract` with the model, query, transport (MCP remote/local or REST),
and result counts. API keys are never included in run payloads, and a tracing
outage can never break the traced call.

## Why Ghost

- **Memory that compounds** across every session and every agent you use.
- **Approval-first autonomy** — observe, prepare, inject, act, with you setting the ceiling.
- **Local-first privacy** — your data lives in a SQLite file on your disk; secrets encrypted; cloud is opt-in per connection.
- **Runs on free models** — local Ollama/llama.cpp or the OpenCode CLI's free tiers; swap providers without rewriting anything.

## Capabilities at a glance

- **Stealth Loop** (`ghostchimera/stealth/`) — Event Fabric, WorldState, Experience Graph, Workflow Learner, Prediction Engine, Stealth Evaluator, Context Fabric, Background Runtime, host adapters (Claude Code, OpenClaw, OpenCode, Codex, Gemini, Hermes), and local IPC transport.
- **Computer use** — browser (console-managed debuggable Chrome), desktop (PyAutoGUI), and vision hierarchy with capability allowlists, risk classification, and explicit approvals.
- **Connectors** (`ghostchimera/connectors/`) — GitHub (poll + webhooks), self-hosted OAuth2 + token vault (Slack, Notion, LinkedIn, GitHub, Google, Zendesk, Freshdesk, Gorgias, HubSpot, Salesforce, Airtable, Hubstaff, Time Doctor). See [docs/CUSTOM_AUTH.md](docs/CUSTOM_AUTH.md).
- **Durable local database** — SQLite/WAL journal for events, interventions, outcomes, and workflows, including the useful-intervention-rate metric. No server required.
- **30+ model providers** — OpenAI, Anthropic, Gemini, OpenRouter, Nebius Token Factory (NVIDIA Nemotron), Ollama, local runtimes, and the OpenCode CLI bridge; swap or chain them without rewriting code.
- **Ghost Console** — full no-code operator dashboard: guided setup, RAG Builder, Self-Evolution, Trust Runtime, Live Presence, remote control, conversational loop, local models, production readiness.
- **Trust Runtime** — durable run journals, resumable approval checkpoints, capability admission, and eval flywheels. [Details](docs/TRUST_RUNTIME.md)
- **Standing Orders** — scoped reusable autonomy programs with explicit enable/run controls. [Details](docs/STANDING_ORDERS.md)
- **Conservative safety defaults** — shell, network, desktop, and host self-editing are off by default; opt-in host mode is explicit and audited.

## Documentation

> **Note on "MCP":** GHOST's internal `ghostchimera/mcp/` module implements a custom HTTP tool protocol (action/discover/call on 127.0.0.1:3100). It is **not** the standard Model Context Protocol (JSON-RPC over stdio/SSE). The naming is historical. The `ghostchimera mcp` CLI manages trust and approval for external standard-MCP servers; it does not expose a stdio server itself.

- [Usage Guide](docs/USAGE_GUIDE.md) — use cases, everyday recipes, safety model
- [User Tutorial](docs/USER_TUTORIAL.md) — guided first run
- [Quick Start](docs/quick-start.md) — fastest install and launch path
- [Install](docs/INSTALL.md) — install matrix and extras
- [Architecture](docs/ARCHITECTURE.md) — how the layers fit together
- [Provider Auth Vault](docs/PROVIDER_AUTH_VAULT.md) — dashboard-based provider setup
- [Remote Control](docs/REMOTE_CONTROL.md) — paired mobile/messaging commands
- [Production Deployment](docs/PRODUCTION_DEPLOYMENT.md) — guardrails for
  always-on use
- [API Reference](docs/api-reference.md) — generated API docs

## Testing

Run the test suite with pytest:

```bash
python -m pytest tests/
```

See [CLAUDE.md](CLAUDE.md) for the full contributor command reference
(compile check, single-file runs, eval suites).

## Production & SaaS pointers

- Daily Production Maintenance refreshes the compatible model catalog and
  dependency audits: `scripts/update_model_provider_catalog.py` produces
  [docs/model_provider_catalog.md](docs/model_provider_catalog.md), and
  `scripts/audit_dependencies.py` produces
  [docs/dependency_audit.md](docs/dependency_audit.md).
- Public Launch SaaS progress: `ghostchimera saas status`,
  `ghostchimera worker status`, and `docker-compose.saas.yml`. Details:
  [docs/PUBLIC_LAUNCH_SAAS.md](docs/PUBLIC_LAUNCH_SAAS.md).
## Appropriate Uses

- User-supervised automation and assistance for real work in local-first mode.
- Desktop and browser workflows (dry-run by default; live modes require explicit enablement and approvals).
- Governed repository change workflows: evidence retrieval → plan → policy checks → PR-ready output.
- Production automation inside externally isolated, reviewed deployments that pass `ghostchimera doctor --production`.
- Extending Ghost Chimera with new backends, skills, and connectors.

## Non-Goals And Boundaries

- Untrusted prompts, repositories, or code must run inside external isolation, not directly on a host machine.
- Ghost Chimera does not claim AGI, subjective consciousness, or fully autonomous operation.
- Commercial and enterprise deployments are expected to pass production guardrails and add organization-specific controls.
- Optional simulator support is not access to a proprietary quantum operating system.

---

## License

MIT — see `LICENSE`. Third-party attribution in `NOTICE`.
