uclone-x 0.2.0__tar.gz → 0.2.2__tar.gz

{uclone_x-0.2.0 → uclone_x-0.2.2}/CHANGELOG.md

@@ -13,6 +13,128 @@ names does.
 Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Each date is
 the date that version was published.
 
+## [0.2.2] - 2026-09-24
+
+### Added
+
+- `ucx install` and `ucx start` now save the model they set up as the default, so
+  `ucx run`, `ucx room`, `ucx loop`, `ucx acp` and `ucx a2a` use it without `--provider`
+  or `--model`, and say which saved model they are using (`ucx acp` and `ucx a2a` on
+  stderr). A model already saved, for example in the dashboard's Settings, is kept; when
+  it differs from the one setup just prepared, setup says both and how to switch. A
+  dashboard that was started with no model picks up a default saved later.
+- `ucx llm use <model>` (with `--provider` and `--base-url`) changes the saved default.
+  It is the same setting as the dashboard's Settings. Command-line flags and environment
+  variables such as `LLM_PROVIDER`, `OLLAMA_MODEL` or a provider's API key variable still
+  come first, and `ucx llm use` says when one of them is set and takes priority.
+- In Settings, the API key field for OpenAI, Anthropic and Gemini links to the page where
+  that provider issues keys, warns when a key does not look like one for the chosen
+  provider or confirms that its format is right, and removes spaces and one pair of quotes
+  from the ends of a pasted key.
+- `ucx key list` shows whether `GEMINI_API_KEY` (or `GOOGLE_API_KEY`),
+  `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` are set. `ucx key setup` opens the provider's
+  key page and writes the key you paste to a `.env` file: the nearest one in this folder
+  or above it, looking no higher than the top of the enclosing git checkout, where it
+  creates one if none is found. Outside a git checkout, it creates one in this folder if
+  none is found above. UClone-X does not read that file itself; load it into your shell,
+  or enter the key in Settings, for the key to be used.
+- Every clone may load the skills approved for it, without `load_skill` in its tool list,
+  and Scout can read web pages as well as search.
+
+### Changed
+
+- Ollama requests now ask for a 16K-token context window, unless `context_limit` or
+  `OLLAMA_CONTEXT_LENGTH` sets another, instead of leaving the size to Ollama, whose own
+  default was 4K on the machine the README's figures come from. A clone's request with
+  tool results then fits. It costs memory: for `qwen3:8b`, about 1.8 GB more than a 4K
+  window (an estimate, not a measurement).
+- The built-in clones Scout, Pioneer, Guardian and Writer have rewritten instructions,
+  now written entirely in English; they still answer in the language you write in. With
+  a Qwen model, clones are also told not to use tools that change files or other state
+  for advice, brainstorming or general reasoning unless you ask for that change, to use
+  read-only search and inspection tools when an answer needs evidence from the workspace
+  or the web, and to answer in the language of the question. They are told that accuracy
+  requirements alone are no reason to decline a reasonable request, to follow your
+  instructions and style without imposing their own judgments, to give substantive
+  answers, and not to add moral lectures, unsolicited caveats or boilerplate disclaimers.
+- The conversation list shows compact times ("now", "5m", "1d", "2w"), and a row's
+  rename and delete buttons appear when you point at the row or move keyboard focus to
+  it, so titles have more room.
+
+### Fixed
+
+- Local image generation on an NVIDIA card now runs on the GPU in half precision, where
+  0.2.1 ran it on the CPU. The engine tries CUDA, then Apple's MPS, then the CPU;
+  `ucx media status` names the device it will use, and image results name the GPU.
+- When less than about 10 GB of GPU memory is free (an estimate), for example because
+  Ollama is keeping a model loaded on the same card, the image engine keeps SDXL's parts
+  in system memory, moves each onto the card only while it runs, and decodes the image in
+  tiles. This needs `accelerate`, which is now installed with the image engine. It is
+  slower and can still run out of memory; if it does, the image request fails with a
+  plain message and the memory is released, and when `accelerate` is missing the message
+  says how to add it.
+- Under WSL2, the free GPU memory used for that decision now counts memory held by other
+  processes (read with NVML or `nvidia-smi`), so the image engine switches to the
+  low-memory mode when another program holds the card. When neither can be read, it uses
+  the low-memory mode.
+- A model that Ollama cannot give tools to (for example `deepseek-r1:14b`) now ends the
+  turn with a short message naming the model and suggesting one that can use tools, such
+  as `qwen3:8b`, plus where to change it: `--model` for `ucx run`,
+  `ucx room retry <id> --model <model>` in a room, and Settings in the dashboard and in an
+  ACP client. The dashboard gives that remedy instead of offering a Retry that would fail
+  the same way.
+- The one-line install now offers the image engine, which the published package
+  includes; 0.2.1 skipped it. When the installer reports success but the engine's core
+  packages (Pillow, diffusers, torch and transformers) cannot be imported, it says so
+  instead of reporting the engine installed. That check does not cover `accelerate`.
+- Setting up Ollama runs its official installer up to 3 times when the download is cut
+  off, with a message between attempts. An attempt that runs out the 15-minute limit is
+  not repeated.
+- A saved API key is used only with the provider it was saved for, and changing provider
+  with `ucx llm use` keeps it.
+
+### Compatibility
+
+- `settings.json` written by 0.2.2 can carry `llm_api_key_provider`, which 0.2.1
+  ignores: 0.2.1 applies a saved API key to whichever provider is saved, and a Settings
+  save in 0.2.1 removes the field. 0.2.1's terminal commands also do not read the saved
+  default.
+- A conversation that contains a turn refused because its model cannot use tools records
+  a reason 0.2.1 does not know, so 0.2.1 may not open it.
+
+## [0.2.1] - 2026-09-24
+
+### Added
+
+- A one-line install. `curl -fsSL https://raw.githubusercontent.com/UClone-AI/uclone-x/main/install.sh | bash`
+  asks its questions on the terminal even when piped, puts a `ucx` command in
+  `~/.local/bin` (and says how to add that folder to `PATH` when it is not there), and
+  ends by offering to start UClone-X. `--no-start` skips that last question.
+- Autonomous discussion in group chats. A toggle in the conversation header lets the
+  clones keep talking among themselves. It pauses while you are not viewing the
+  conversation, resumes when you come back, and stops after 20 turns in a row without you.
+- While a clone runs a tool, the conversation shows which one instead of "Thinking...".
+- The artist clone can remember characters: a `character_sheet` tool saves each
+  character's look (tags, description, seed) as a file under `characters/` in the
+  workspace, reuses it in later images, and combines several saved characters into one
+  scene prompt. It now writes image prompts in English and chooses the aspect ratio from
+  the subject.
+- In a group chat, the model that picks the next speaker is now told to let another clone
+  answer a question one clone asks, instead of ending the exchange, and to start a
+  discussion when you ask the clones to talk among themselves.
+- With developer mode on, a turn shows the model calls it made: model, tokens, duration
+  and tools called for each, and on expanding one, the request, the tools offered and the
+  response.
+
+### Fixed
+
+- Choosing the next speaker in a group chat now asks Ollama to turn a reasoning model's
+  thinking off (for example Qwen3), so it replies without spending its budget on
+  reasoning first. A selector that runs out of tokens now says so instead of reporting a
+  missing JSON object.
+- The message shown when no model is available points to Settings, and to `ucx llm status`
+  from a terminal, instead of a `./ucx` command that does not exist in an installed copy.
+
 ## [0.2.0] - 2026-09-24
 
 ### Added

{uclone_x-0.2.0 → uclone_x-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: uclone-x
-Version: 0.2.0
+Version: 0.2.2
 Summary: Next-Generation Event-Driven AI Agent Core & High-Performance Collaboration Framework
 Author-email: Kenny Lim <kennylim@uclone.net>
 License-Expression: Apache-2.0
@@ -21,6 +21,7 @@ Requires-Dist: pydantic-settings>=2.2.0
 Requires-Dist: pydantic>=2.7.0
 Requires-Dist: pyyaml>=6.0.1
 Provides-Extra: all
+Requires-Dist: accelerate>=0.31.0; extra == 'all'
 Requires-Dist: anthropic>=0.25.0; extra == 'all'
 Requires-Dist: diffusers>=0.31.0; extra == 'all'
 Requires-Dist: fastapi>=0.110.0; extra == 'all'
@@ -71,6 +72,7 @@ Requires-Dist: anthropic>=0.25.0; extra == 'llm'
 Requires-Dist: google-genai>=0.1.0; extra == 'llm'
 Requires-Dist: openai>=1.25.0; extra == 'llm'
 Provides-Extra: media
+Requires-Dist: accelerate>=0.31.0; extra == 'media'
 Requires-Dist: diffusers>=0.31.0; extra == 'media'
 Requires-Dist: pillow>=10.0.0; extra == 'media'
 Requires-Dist: torch>=2.2.0; extra == 'media'
@@ -101,66 +103,80 @@ Description-Content-Type: text/markdown
 
 ## Install
 
+On macOS or Linux, paste this into a terminal:
+
 ```bash
-uv tool install --managed-python --python 3.12 "uclone-x[cli,http]"
-ucx --help
+curl -fsSL https://raw.githubusercontent.com/UClone-AI/uclone-x/main/install.sh | bash
 ```
 
-Or `uvx --managed-python --python 3.12 --from "uclone-x[cli,http]" ucx --help` to try
-it without installing anything permanently. Keep both flags: without `--python 3.12` uv
-uses the first `python3` on PATH, which on macOS is 3.9, and the install fails; without
-`--managed-python` it still runs that `python3` to check its version, and on a Mac
-without the Xcode Command Line Tools that opens an install dialog. With both, uv
-downloads its own Python 3.12 and touches nothing else.
+That is the whole install. It needs nothing but `curl` — no Python, Homebrew or
+admin rights of its own. It installs the core (~31 MB), then asks before each
+larger download: a private Python 3.12 when your machine has nothing newer than
+3.10, then a local AI model through Ollama (~1.4–5.2 GB, depending on memory; say
+no to use an API key instead). Ollama's own installer may ask for your password.
+At the end it asks **Start UClone-X now?** — press Enter, answer any remaining
+setup question, and the dashboard opens in your browser at
+<http://127.0.0.1:5180>. The agents work in the folder you ran it from.
 
-The two extras are not optional in practice: `cli` is typer and rich, which the
-`ucx` shell is written in, and `http` is FastAPI and uvicorn, which the
-dashboard and the A2A gateway serve through. The base install is the runtime
-without a shell — usable as a library, and what you want if you are importing
-`uclone_x` rather than running `ucx`. Install without them and `ucx` tells you
-which one is missing rather than failing obscurely.
+To answer, UClone-X needs a model: the local one above, which needs no account,
+or an API key for OpenAI, Anthropic or Gemini, pasted into the dashboard's
+**Settings**. Nothing needs editing in a file.
 
-Provider SDKs and the heavier stacks are the genuinely optional extras — install
-what you use:
+Next time, start it with:
 
 ```bash
-pip install "uclone-x[llm]"         # Gemini, Claude, OpenAI SDKs
-pip install "uclone-x[ontology]"    # LinkML, rdflib, networkx
-pip install "uclone-x[code_intel]"  # tree-sitter AST parsing
-pip install "uclone-x[all]"
+ucx start
 ```
 
-Python 3.11 or newer, and every extra resolves on every version of it, 3.13
-included. `code_intel` used to be capped at 3.12, because the grammar bundle it
-declared — `tree-sitter-languages` — publishes no wheel above cp312, and since
-`all` includes `code_intel` that ceiling was `uclone-x[all]`'s too. It now
-declares `tree-sitter-language-pack`, which ships cp313 wheels, so neither is
-capped. Without the extra the AST parser falls back to Python's own `ast` and
-says so.
+If your shell says `command not found`, the installer printed one `export PATH=…`
+line at the end; add it to `~/.zshrc` (or `~/.bashrc`) and open a new terminal.
+Until then, `~/.local/bin/ucx start` works.
+
+UClone-X itself lives in `~/.uclone-x` and the `ucx` link in `~/.local/bin`;
+`rm -rf ~/.uclone-x ~/.local/bin/ucx` removes it. What the installer fetched
+alongside it stays: uv (`~/.local/bin/uv`, `uvx`) and the Python it downloaded
+(`uv python uninstall 3.12` removes that), and Ollama with its models.
 
-## First run
+### Other ways to install
 
-Configure at least one provider, then start a chat session:
+If you already use [uv](https://docs.astral.sh/uv/):
 
 ```bash
-cp .env.example .env    # then fill in one API key, or point at a local Ollama
-ucx run
+uv tool install --managed-python --python 3.12 "uclone-x[cli,http]"
+ucx start
 ```
 
-`ucx run` is an interactive terminal REPL with streaming responses, tool calls
-and slash commands. A local model needs no API key at all:
+Keep both flags: without `--python 3.12` uv uses the first `python3` on PATH,
+which on macOS is 3.9, and the install fails; without `--managed-python` it still
+runs that `python3` to check its version, and on a Mac without the Xcode Command
+Line Tools that opens an install dialog.
+
+With pip, into a Python 3.11+ environment of your own:
+`pip install "uclone-x[cli,http]"`. The two extras are not optional in practice:
+`cli` is the `ucx` shell and `http` serves the dashboard. The base install is the
+runtime without a shell — what you want if you are importing `uclone_x` as a
+library. Provider SDKs and the heavier stacks are the genuinely optional extras:
 
 ```bash
-OLLAMA_FAST_BASE_URL=http://localhost:11434/v1 OLLAMA_FAST_MODEL=qwen3:8b ucx run
+pip install "uclone-x[llm]"         # Gemini, Claude, OpenAI SDKs
+pip install "uclone-x[ontology]"    # LinkML, rdflib, networkx
+pip install "uclone-x[code_intel]"  # tree-sitter AST parsing
+pip install "uclone-x[all]"
 ```
 
-The dashboard — an agent and event-bus explorer — is a single command:
+Every extra resolves on Python 3.11, 3.12 and 3.13.
+
+### From a terminal
+
+`ucx run` is an interactive terminal REPL with streaming responses, tool calls
+and slash commands. It reads its model from the environment — an API key such as
+`OPENAI_API_KEY`, or a local Ollama:
 
 ```bash
-ucx ui
+OLLAMA_FAST_BASE_URL=http://localhost:11434/v1 OLLAMA_FAST_MODEL=qwen3:8b ucx run
 ```
 
-It serves a prebuilt interface, so it needs no Node toolchain.
+`ucx llm status` reports which models are reachable.
 
 ## What UClone-X is
 

{uclone_x-0.2.0 → uclone_x-0.2.2}/README.md

@@ -14,66 +14,80 @@
 
 ## Install
 
+On macOS or Linux, paste this into a terminal:
+
 ```bash
-uv tool install --managed-python --python 3.12 "uclone-x[cli,http]"
-ucx --help
+curl -fsSL https://raw.githubusercontent.com/UClone-AI/uclone-x/main/install.sh | bash
 ```
 
-Or `uvx --managed-python --python 3.12 --from "uclone-x[cli,http]" ucx --help` to try
-it without installing anything permanently. Keep both flags: without `--python 3.12` uv
-uses the first `python3` on PATH, which on macOS is 3.9, and the install fails; without
-`--managed-python` it still runs that `python3` to check its version, and on a Mac
-without the Xcode Command Line Tools that opens an install dialog. With both, uv
-downloads its own Python 3.12 and touches nothing else.
+That is the whole install. It needs nothing but `curl` — no Python, Homebrew or
+admin rights of its own. It installs the core (~31 MB), then asks before each
+larger download: a private Python 3.12 when your machine has nothing newer than
+3.10, then a local AI model through Ollama (~1.4–5.2 GB, depending on memory; say
+no to use an API key instead). Ollama's own installer may ask for your password.
+At the end it asks **Start UClone-X now?** — press Enter, answer any remaining
+setup question, and the dashboard opens in your browser at
+<http://127.0.0.1:5180>. The agents work in the folder you ran it from.
 
-The two extras are not optional in practice: `cli` is typer and rich, which the
-`ucx` shell is written in, and `http` is FastAPI and uvicorn, which the
-dashboard and the A2A gateway serve through. The base install is the runtime
-without a shell — usable as a library, and what you want if you are importing
-`uclone_x` rather than running `ucx`. Install without them and `ucx` tells you
-which one is missing rather than failing obscurely.
+To answer, UClone-X needs a model: the local one above, which needs no account,
+or an API key for OpenAI, Anthropic or Gemini, pasted into the dashboard's
+**Settings**. Nothing needs editing in a file.
 
-Provider SDKs and the heavier stacks are the genuinely optional extras — install
-what you use:
+Next time, start it with:
 
 ```bash
-pip install "uclone-x[llm]"         # Gemini, Claude, OpenAI SDKs
-pip install "uclone-x[ontology]"    # LinkML, rdflib, networkx
-pip install "uclone-x[code_intel]"  # tree-sitter AST parsing
-pip install "uclone-x[all]"
+ucx start
 ```
 
-Python 3.11 or newer, and every extra resolves on every version of it, 3.13
-included. `code_intel` used to be capped at 3.12, because the grammar bundle it
-declared — `tree-sitter-languages` — publishes no wheel above cp312, and since
-`all` includes `code_intel` that ceiling was `uclone-x[all]`'s too. It now
-declares `tree-sitter-language-pack`, which ships cp313 wheels, so neither is
-capped. Without the extra the AST parser falls back to Python's own `ast` and
-says so.
+If your shell says `command not found`, the installer printed one `export PATH=…`
+line at the end; add it to `~/.zshrc` (or `~/.bashrc`) and open a new terminal.
+Until then, `~/.local/bin/ucx start` works.
+
+UClone-X itself lives in `~/.uclone-x` and the `ucx` link in `~/.local/bin`;
+`rm -rf ~/.uclone-x ~/.local/bin/ucx` removes it. What the installer fetched
+alongside it stays: uv (`~/.local/bin/uv`, `uvx`) and the Python it downloaded
+(`uv python uninstall 3.12` removes that), and Ollama with its models.
 
-## First run
+### Other ways to install
 
-Configure at least one provider, then start a chat session:
+If you already use [uv](https://docs.astral.sh/uv/):
 
 ```bash
-cp .env.example .env    # then fill in one API key, or point at a local Ollama
-ucx run
+uv tool install --managed-python --python 3.12 "uclone-x[cli,http]"
+ucx start
 ```
 
-`ucx run` is an interactive terminal REPL with streaming responses, tool calls
-and slash commands. A local model needs no API key at all:
+Keep both flags: without `--python 3.12` uv uses the first `python3` on PATH,
+which on macOS is 3.9, and the install fails; without `--managed-python` it still
+runs that `python3` to check its version, and on a Mac without the Xcode Command
+Line Tools that opens an install dialog.
+
+With pip, into a Python 3.11+ environment of your own:
+`pip install "uclone-x[cli,http]"`. The two extras are not optional in practice:
+`cli` is the `ucx` shell and `http` serves the dashboard. The base install is the
+runtime without a shell — what you want if you are importing `uclone_x` as a
+library. Provider SDKs and the heavier stacks are the genuinely optional extras:
 
 ```bash
-OLLAMA_FAST_BASE_URL=http://localhost:11434/v1 OLLAMA_FAST_MODEL=qwen3:8b ucx run
+pip install "uclone-x[llm]"         # Gemini, Claude, OpenAI SDKs
+pip install "uclone-x[ontology]"    # LinkML, rdflib, networkx
+pip install "uclone-x[code_intel]"  # tree-sitter AST parsing
+pip install "uclone-x[all]"
 ```
 
-The dashboard — an agent and event-bus explorer — is a single command:
+Every extra resolves on Python 3.11, 3.12 and 3.13.
+
+### From a terminal
+
+`ucx run` is an interactive terminal REPL with streaming responses, tool calls
+and slash commands. It reads its model from the environment — an API key such as
+`OPENAI_API_KEY`, or a local Ollama:
 
 ```bash
-ucx ui
+OLLAMA_FAST_BASE_URL=http://localhost:11434/v1 OLLAMA_FAST_MODEL=qwen3:8b ucx run
 ```
 
-It serves a prebuilt interface, so it needs no Node toolchain.
+`ucx llm status` reports which models are reachable.
 
 ## What UClone-X is
 

{uclone_x-0.2.0 → uclone_x-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "uclone-x"
-version = "0.2.0"
+version = "0.2.2"
 description = "Next-Generation Event-Driven AI Agent Core & High-Performance Collaboration Framework"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -101,8 +101,14 @@ ontology = [
 # `ucx media status` reporting ready for an engine that would fail on `import torch`.
 # The floors here are the same ones `IN_PROCESS_REQUIREMENTS` checks at runtime, so a
 # beginner who installs this extra and a beginner who follows the hint end up equivalent.
+#
+# `accelerate` is what `enable_model_cpu_offload` needs. It is not a runtime requirement
+# (MPS and CPU never offload, and a CUDA card with room loads the whole pipeline), so it is
+# not in `IN_PROCESS_REQUIREMENTS`; it is here so an NVIDIA card whose memory is shared
+# with a resident Ollama model can still run SDXL instead of running out of memory.
 media = [
     "pillow>=10.0.0",
+    "accelerate>=0.31.0",
     "diffusers>=0.31.0",
     "torch>=2.2.0",
     "transformers>=4.40.0",

{uclone_x-0.2.0 → uclone_x-0.2.2}/src/uclone_x/__init__.py

@@ -1,5 +1,5 @@
 """UClone-X: Next-Generation Event-Driven AI Agent Core & Collaboration Framework."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 __author__ = "Kenny Lim <kennylim@uclone.net>"
 __all__ = ["__version__"]