nexu 0.2.5__tar.gz

nexu-0.2.5/.gitignore

@@ -0,0 +1,24 @@
+.idea/nexu.iml
+.idea/pyProjectModel.xml
+.idea/misc.xml
+.env.example
+.idea/inspectionProfiles/Project_Default.xml
+.idea/inspectionProfiles/profiles_settings.xml
+.idea/modules.xml
+.idea/vcs.xml
+.idea/vico.iml
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.coverage
+htmlcov/
+
+# Environment variables
+.env

nexu-0.2.5/.idea/.gitignore

@@ -0,0 +1,5 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/

nexu-0.2.5/.idea/workspace.xml

@@ -0,0 +1,155 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="AutoImportSettings">
+    <option name="autoReloadType" value="SELECTIVE" />
+  </component>
+  <component name="ChangeListManager">
+    <list default="true" id="d6578b4a-a4c2-4076-bba1-42ee09a831d5" name="Changes" comment="">
+      <change beforePath="$PROJECT_DIR$/pyproject.toml" beforeDir="false" afterPath="$PROJECT_DIR$/pyproject.toml" afterDir="false" />
+    </list>
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="ChangesViewManager">
+    <option name="groupingKeys">
+      <option value="directory" />
+      <option value="repository" />
+    </option>
+  </component>
+  <component name="EmbeddingIndexingInfo">
+    <option name="cachedIndexableFilesCount" value="65" />
+    <option name="fileBasedEmbeddingIndicesEnabled" value="true" />
+  </component>
+  <component name="Git.Settings">
+    <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
+  </component>
+  <component name="GitHubPullRequestSearchHistory"><![CDATA[{
+  "lastFilter": {
+    "state": "OPEN",
+    "assignee": "tom-sapletta-com"
+  }
+}]]></component>
+  <component name="GithubPullRequestsUISettings"><![CDATA[{
+  "selectedUrlAndAccountId": {
+    "url": "git@github.com:semcod/vico.git",
+    "accountId": "b26609e8-3115-4862-a267-55cedfdb14bb"
+  }
+}]]></component>
+  <component name="McpProjectServerCommands">
+    <commands />
+    <urls />
+  </component>
+  <component name="NextEditCompletionFeaturesState">
+    <decayedCancelled>
+      <entry key="MS100" value="1.000000062898032" />
+      <entry key="MS500" value="1.1029466047308847" />
+      <entry key="S2" value="2.5963335556772167" />
+      <entry key="S5" value="3.7692254290316294" />
+      <entry key="S10" value="4.329749576774056" />
+      <entry key="S30" value="5.114106888875041" />
+      <entry key="S60" value="6.302837674181121" />
+      <entry key="M2" value="8.220943940018103" />
+      <entry key="M5" value="11.149919160624908" />
+      <entry key="M10" value="13.204089594609442" />
+      <entry key="M15" value="14.36089495737726" />
+      <entry key="M30" value="16.107056328331147" />
+      <entry key="H1" value="17.35765299817043" />
+      <entry key="H2" value="18.121051695991305" />
+      <entry key="H4" value="18.544800600698565" />
+      <entry key="D1" value="18.92183095293997" />
+      <entry key="W1" value="18.988774992217735" />
+    </decayedCancelled>
+    <decayedSelected>
+      <entry key="MS100" value="0.0" />
+      <entry key="MS500" value="0.0" />
+      <entry key="S2" value="0.0" />
+      <entry key="S5" value="0.0" />
+      <entry key="S10" value="0.0" />
+      <entry key="S30" value="0.0" />
+      <entry key="S60" value="0.0" />
+      <entry key="M2" value="0.0" />
+      <entry key="M5" value="0.0" />
+      <entry key="M10" value="0.0" />
+      <entry key="M15" value="0.0" />
+      <entry key="M30" value="0.0" />
+      <entry key="H1" value="0.0" />
+      <entry key="H2" value="0.0" />
+      <entry key="H4" value="0.0" />
+      <entry key="D1" value="0.0" />
+      <entry key="W1" value="0.0" />
+    </decayedSelected>
+    <decayedShown>
+      <entry key="MS100" value="0.9794203590556573" />
+      <entry key="MS500" value="1.0983293227111324" />
+      <entry key="S2" value="2.5934928533336956" />
+      <entry key="S5" value="3.7675609844256748" />
+      <entry key="S10" value="4.328791119054477" />
+      <entry key="S30" value="5.113719136711925" />
+      <entry key="S60" value="6.302582198552924" />
+      <entry key="M2" value="8.2207593976687" />
+      <entry key="M5" value="11.149803608335493" />
+      <entry key="M10" value="13.204005506235976" />
+      <entry key="M15" value="14.36082382411727" />
+      <entry key="M30" value="16.107006691794044" />
+      <entry key="H1" value="17.357622487370417" />
+      <entry key="H2" value="18.121034612225742" />
+      <entry key="H4" value="18.544791539568454" />
+      <entry key="D1" value="18.921829364722782" />
+      <entry key="W1" value="18.9887747633369" />
+    </decayedShown>
+  </component>
+  <component name="ProjectColorInfo">{
+  &quot;associatedIndex&quot;: 0,
+  &quot;fromUser&quot;: false
+}</component>
+  <component name="ProjectId" id="3EPL5mtMuK2XSqut5C82Jr7mQTL" />
+  <component name="ProjectViewState">
+    <option name="autoscrollFromSource" value="true" />
+    <option name="autoscrollToSource" value="true" />
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent"><![CDATA[{
+  "keyToString": {
+    "ModuleVcsDetector.initialDetectionPerformed": "true",
+    "RunOnceActivity.MCP Project settings loaded": "true",
+    "RunOnceActivity.ShowReadmeOnStart": "true",
+    "RunOnceActivity.TerminalTabsStorage.copyFrom.TerminalArrangementManager.252": "true",
+    "RunOnceActivity.git.unshallow": "true",
+    "RunOnceActivity.typescript.service.memoryLimit.init": "true",
+    "codeWithMe.voiceChat.enabledByDefault": "false",
+    "git-widget-placeholder": "main",
+    "last_opened_file_path": "/home/tom/github/semcod/nexu",
+    "node.js.detected.package.eslint": "true",
+    "node.js.selected.package.eslint": "(autodetect)",
+    "nodejs_package_manager_path": "npm"
+  }
+}]]></component>
+  <component name="RecentsManager">
+    <key name="CopyFile.RECENT_KEYS">
+      <recent name="$PROJECT_DIR$" />
+    </key>
+  </component>
+  <component name="SharedIndexes">
+    <attachedChunks>
+      <set>
+        <option value="bundled-python-sdk-c59985aa861c-c2ffad84badb-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-261.24374.152" />
+      </set>
+    </attachedChunks>
+  </component>
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <changelist id="d6578b4a-a4c2-4076-bba1-42ee09a831d5" name="Changes" comment="" />
+      <created>1780075077718</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1780075077718</updated>
+    </task>
+    <servers />
+  </component>
+  <component name="TypeScriptGeneratedFilesManager">
+    <option name="version" value="3" />
+  </component>
+</project>

nexu-0.2.5/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.2.5] - 2026-05-29
+
+### Docs
+- Update README.md
+
+### Test
+- Update tests/test_vico.py
+
+### Other
+- Update .idea/nexu.iml
+- Update .idea/pyProjectModel.xml
+
+## [0.2.4] - 2026-05-29
+
+### Other
+- Update .idea/misc.xml
+- Update uv.lock
+
+## [0.2.3] - 2026-05-29
+
+### Docs
+- Update README.md
+
+## [0.2.2] - 2026-05-29
+
+### Docs
+- Update README.md
+
+## [0.2.1] - 2026-05-29
+
+### Docs
+- Update CHANGELOG.md
+- Update README.md
+- Update docs/architecture.md
+- Update docs/capsule-format.md
+- Update docs/commands.md
+- Update docs/examples.md
+- Update docs/getting-started.md
+- Update docs/roadmap.md
+- Update docs/verification.md
+
+### Test
+- Update tests/test_capsule_next_stage.py
+
+### Other
+- Update VERSION
+- Update examples/run_examples.py
+- Update uv.lock
+
+
+## 0.2.0
+
+- Added capsule baseline hash lock.
+- Added `capsule status`.
+- Added `capsule blueprint`.
+- Added `capsule export-prompt`.
+- Added `capsule diff`.
+- Added `capsule drift`.
+- Improved verification gates and evidence output.
+
+## 0.1.0
+
+- Initial project skeleton.
+- Added freeze, capsule create, iterate, verify and promote dry-run.

nexu-0.2.5/LICENSE

@@ -0,0 +1,16 @@
+Apache License
+Version 2.0, January 2004
+
+Copyright 2026 Vico contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

nexu-0.2.5/Makefile

@@ -0,0 +1,7 @@
+.PHONY: test examples
+
+test:
+	pytest -q
+
+examples:
+	python examples/run_examples.py

nexu-0.2.5/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: nexu
+Version: 0.2.5
+Summary: Visual Intent Contract Orchestrator: freeze project slices, evolve capsules, verify intent contracts.
+Author-email: Tom Sapletta <tom@sapletta.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: capsule,contracts,intent,llm,mock,static-analysis,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: costs>=0.1.20; extra == 'dev'
+Requires-Dist: goal>=2.1.0; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pfix>=0.1.60; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: litellm>=1.0; extra == 'llm'
+Provides-Extra: watch
+Requires-Dist: watchdog>=4.0; extra == 'watch'
+Description-Content-Type: text/markdown
+
+# Vico
+
+
+## AI Cost Tracking
+
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.5-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.51-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-2.3h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+
+- 🤖 **LLM usage:** $0.5133 (5 commits)
+- 👤 **Human dev:** ~$231 (2.3h @ $100/h, 30min dedup)
+
+Generated on 2026-05-29 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
+
+---
+
+**Vico** — **Visual Intent Contract Orchestrator**.
+
+Vico is a Python package and CLI for creating small, isolated project capsules from a large codebase.
+It helps you freeze a baseline, extract a slice of code/data/contracts, evolve that slice through multiple
+LLM or human iterations, and verify the result against formal intent contracts before promoting it back.
+
+The core workflow is:
+
+```text
+freeze → capsule create → blueprint → iterate → export-prompt → verify → promote
+```
+
+Vico is designed to work with **Intract**-style intent contracts, but it can run as a standalone prototype.
+The goal is not to make an LLM magically correct. The goal is to keep the LLM inside a small, versioned,
+contract-bound sandbox and detect when its output diverges from declared intent.
+
+## What changed in 0.2.0
+
+The second iteration adds the missing practical loop around capsules:
+
+- baseline hash lock per capsule,
+- capsule diff against the frozen slice,
+- source drift check against the original files,
+- generated UI/API/test blueprint,
+- LLM-ready prompt export,
+- capsule status command,
+- richer verification with evidence for outputs, forbidden effects, required intents and secret-like values.
+
+## Why Vico?
+
+Long-running IDE prompting has a common failure mode:
+
+```text
+large repo + vague task + many steps = context drift and hallucinated implementation
+```
+
+Vico changes the operating model:
+
+```text
+large repo
+  ↓ freeze baseline
+small capsule
+  ↓ evolve only this capsule
+verified result
+  ↓ promote to the real project
+```
+
+## Install locally
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e .[dev]
+vico --help
+```
+
+## First run
+
+```bash
+vico init .
+vico freeze . --name baseline
+vico capsule create . --name menu-icons --domain menu --include "examples/frontend_view/src/**" --route /menu-icons
+vico capsule blueprint menu-icons --print
+vico capsule iterate menu-icons --steps 3 --goal "Add preview, confidence and reason fields"
+vico capsule export-prompt menu-icons
+vico capsule verify menu-icons
+vico capsule diff menu-icons
+vico capsule drift menu-icons
+vico capsule promote menu-icons --dry-run
+```
+
+## Important folders
+
+```text
+src/vico/       Python package
+docs/           documentation
+examples/       runnable example projects
+tests/          unit tests
+```
+
+## Documentation
+
+Start here:
+
+- [Docs index](docs/README.md)
+- [Getting started](docs/getting-started.md)
+- [Architecture](docs/architecture.md)
+- [Commands](docs/commands.md)
+- [Capsule format](docs/capsule-format.md)
+- [Intent contracts](docs/intent-contracts.md)
+- [Verification model](docs/verification.md)
+- [Examples](docs/examples.md)
+- [Roadmap](docs/roadmap.md)
+
+## Main commands
+
+```bash
+vico init .
+vico freeze . --name baseline
+vico capsule create . --name my-slice --include "src/my_module/**"
+vico capsule list
+vico capsule status my-slice
+vico capsule blueprint my-slice
+vico capsule iterate my-slice --steps 10 --goal "Evolve final screen"
+vico capsule export-prompt my-slice
+vico capsule diff my-slice
+vico capsule drift my-slice
+vico capsule verify my-slice
+vico capsule promote my-slice --dry-run
+```
+
+## License
+
+Licensed under Apache-2.0.

nexu-0.2.5/README.md

@@ -0,0 +1,129 @@
+# Vico
+
+
+## AI Cost Tracking
+
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.5-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.51-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-2.3h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+
+- 🤖 **LLM usage:** $0.5133 (5 commits)
+- 👤 **Human dev:** ~$231 (2.3h @ $100/h, 30min dedup)
+
+Generated on 2026-05-29 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
+
+---
+
+**Vico** — **Visual Intent Contract Orchestrator**.
+
+Vico is a Python package and CLI for creating small, isolated project capsules from a large codebase.
+It helps you freeze a baseline, extract a slice of code/data/contracts, evolve that slice through multiple
+LLM or human iterations, and verify the result against formal intent contracts before promoting it back.
+
+The core workflow is:
+
+```text
+freeze → capsule create → blueprint → iterate → export-prompt → verify → promote
+```
+
+Vico is designed to work with **Intract**-style intent contracts, but it can run as a standalone prototype.
+The goal is not to make an LLM magically correct. The goal is to keep the LLM inside a small, versioned,
+contract-bound sandbox and detect when its output diverges from declared intent.
+
+## What changed in 0.2.0
+
+The second iteration adds the missing practical loop around capsules:
+
+- baseline hash lock per capsule,
+- capsule diff against the frozen slice,
+- source drift check against the original files,
+- generated UI/API/test blueprint,
+- LLM-ready prompt export,
+- capsule status command,
+- richer verification with evidence for outputs, forbidden effects, required intents and secret-like values.
+
+## Why Vico?
+
+Long-running IDE prompting has a common failure mode:
+
+```text
+large repo + vague task + many steps = context drift and hallucinated implementation
+```
+
+Vico changes the operating model:
+
+```text
+large repo
+  ↓ freeze baseline
+small capsule
+  ↓ evolve only this capsule
+verified result
+  ↓ promote to the real project
+```
+
+## Install locally
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e .[dev]
+vico --help
+```
+
+## First run
+
+```bash
+vico init .
+vico freeze . --name baseline
+vico capsule create . --name menu-icons --domain menu --include "examples/frontend_view/src/**" --route /menu-icons
+vico capsule blueprint menu-icons --print
+vico capsule iterate menu-icons --steps 3 --goal "Add preview, confidence and reason fields"
+vico capsule export-prompt menu-icons
+vico capsule verify menu-icons
+vico capsule diff menu-icons
+vico capsule drift menu-icons
+vico capsule promote menu-icons --dry-run
+```
+
+## Important folders
+
+```text
+src/vico/       Python package
+docs/           documentation
+examples/       runnable example projects
+tests/          unit tests
+```
+
+## Documentation
+
+Start here:
+
+- [Docs index](docs/README.md)
+- [Getting started](docs/getting-started.md)
+- [Architecture](docs/architecture.md)
+- [Commands](docs/commands.md)
+- [Capsule format](docs/capsule-format.md)
+- [Intent contracts](docs/intent-contracts.md)
+- [Verification model](docs/verification.md)
+- [Examples](docs/examples.md)
+- [Roadmap](docs/roadmap.md)
+
+## Main commands
+
+```bash
+vico init .
+vico freeze . --name baseline
+vico capsule create . --name my-slice --include "src/my_module/**"
+vico capsule list
+vico capsule status my-slice
+vico capsule blueprint my-slice
+vico capsule iterate my-slice --steps 10 --goal "Evolve final screen"
+vico capsule export-prompt my-slice
+vico capsule diff my-slice
+vico capsule drift my-slice
+vico capsule verify my-slice
+vico capsule promote my-slice --dry-run
+```
+
+## License
+
+Licensed under Apache-2.0.

nexu-0.2.5/VERSION

@@ -0,0 +1 @@
+0.2.5

nexu-0.2.5/docs/README.md

@@ -0,0 +1,14 @@
+# Vico documentation
+
+Vico is a capsule-based orchestration layer for safe LLM-assisted iteration.
+
+Read in this order:
+
+1. [Getting started](getting-started.md)
+2. [Architecture](architecture.md)
+3. [Commands](commands.md)
+4. [Capsule format](capsule-format.md)
+5. [Intent contracts](intent-contracts.md)
+6. [Verification model](verification.md)
+7. [Examples](examples.md)
+8. [Roadmap](roadmap.md)

nexu-0.2.5/docs/architecture.md

@@ -0,0 +1,43 @@
+# Architecture
+
+Vico is a thin orchestration layer around isolated project capsules.
+
+```text
+source project
+  -> freeze snapshot
+  -> capsule selection
+  -> baseline lock
+  -> capsule src + fixtures + contracts
+  -> blueprint / prompt / iteration state
+  -> verification evidence
+  -> promotion plan
+```
+
+## Core modules
+
+- `models.py` — dataclasses for snapshots, capsules, diffs, prompt exports and verification reports.
+- `freeze.py` — creates lightweight file-hash snapshots.
+- `capsule.py` — creates and loads isolated capsules.
+- `blueprint.py` — generates UI/API/test blueprint from capsule metadata and contracts.
+- `iterate.py` — creates S1..Sn iteration folders and prompts.
+- `export_prompt.py` — exports an LLM-ready prompt constrained by Intract contracts.
+- `diff.py` — compares capsule state with baseline lock.
+- `drift.py` — checks whether original source files changed after capsule creation.
+- `verify.py` — builds evidence-based verification reports.
+- `promote.py` — produces a dry-run promotion plan.
+
+## Intract boundary
+
+Vico does not replace Intract. Intract remains the intent-contract layer. Vico uses `@intract.v1` and `intract.yaml` as its formal input and converts them into prompts, blueprints, gates and evidence maps.
+
+## Anti-hallucination principle
+
+LLM output is not trusted directly. It must pass gates based on:
+
+- frozen baseline,
+- selected file scope,
+- declared intent contracts,
+- forbidden effects,
+- required outputs,
+- source drift,
+- verification evidence.