Run and reproduce NEXORA
Run from the repository root. Python >=3.11 is the package baseline; the validated machine uses Python 3.14.6 and CPU PyTorch. Native Windows voice/quantization/backend support varies. Exact observed versions are in requirements-tested.txt; do not assume a CUDA wheel is installed just because an NVIDIA GPU exists.
Setup and quick use
python -m venv .venv
.venv/Scripts/Activate.ps1
python -m pip install -e '.[inference,dev]'
python scripts/download_model.py
python -m nexora.cli chat 'Explain how to verify a code repair.' --model .cache/Qwen3.5-0.8B
python -m nexora.cli index . --query 'checkpoint recovery'
Downloads fetch only a pinned, attributed upstream model; they are not training. The tiny original checkpoint already ships at artifacts/tiny. It is not instruction tuned for useful conversation:
python -m nexora.cli generate 'A reliable program' --checkpoint artifacts/tiny --tokens 40
Reproduce the training milestone
python scripts/make_demo_data.py
python -m nexora.cli prepare examples/corpus.jsonl
python -m nexora.cli train --config configs/tiny.json --output artifacts/reproduction --stop-after 60
python -m nexora.cli train --config configs/tiny.json --output artifacts/reproduction --resume
python scripts/recovery_experiment.py
python scripts/posttrain_experiment.py
python scripts/quantization_experiment.py
Do not overwrite original reports when comparing an experiment unless intended. Training --resume requires identical manifest and training configuration, including planned total steps. --stop-after interrupts at a chosen step without changing the schedule. Recovery restores optimizer and RNG states. Checkpoints live in generation-specific files; latest.json is replaced only after saving/checksumming the new file. A previous generation remains available if a save fails. This is single-process atomic replacement, not distributed/async checkpoint durability.
The adapter experiment saves only experimental low-rank weights. Reconstruct the same reference model and use inject_lora(rank=4, alpha=8) before loading these weights with explicit missing-base-key checks. It is not a PEFT adapter for Qwen and must not be loaded onto Qwen. No toy adapter is enabled by default.
Tests and measurements
$env:PYTEST_DISABLE_PLUGIN_AUTOLOAD='1'
python -m pytest -q --junitxml=reports/pytest.xml
python scripts/benchmark.py --model .cache/Qwen3-0.6B --report baseline
python scripts/benchmark.py --model .cache/Qwen3.5-0.8B --report qwen35
python scripts/stream_benchmark.py
python scripts/research_reports.py
python -m nexora.cli estimate --parameters 120000000000 --tokens 2400000000000 --gpus 1024
Disabling plugin autoload avoids an unrelated globally installed xonsh pytest plugin failing in a noninteractive Windows console. No NEXORA tests require that plugin. The symlink test may skip when Windows privileges prohibit creating symlinks; run on Linux or a Windows developer-mode account before claiming that platform boundary has been exercised.
Agent permissions
Start read-only:
python -m nexora.cli agent 'Inspect the source files and explain the checkpoint mechanism.' --policy configs/policy.readonly.json --model .cache/Qwen3.5-0.8B
Without an independent verifier, completion is labeled unverified. The model may fail to produce schema-valid actions. This is an observed limitation, not a reason to silently execute prose.
For an owner-controlled disposable repository, create a policy with its exact root, permissions and named command argument arrays. Example shape (replace executable/root with your actual paths):
{
"root": "D:/disposable-project",
"permissions": ["READ", "WRITE", "EXECUTE"],
"commands": {"tests": ["C:/Python314/python.exe", "-I", "-m", "pytest", "-q"]},
"timeout_seconds": 30,
"output_limit": 16000,
"max_file_bytes": 200000,
"allow_host_execution": true
}
Then pass --verify-command tests. For hostile tasks this host runner is unsuitable: use an actual isolated execution service and trusted tests outside the writable repository. A green test edited by the model is not an independent oracle. Do not mount secrets or your whole home directory. See docs/SECURITY.md.
External inference is opt-in:
python -m nexora.cli agent 'Inspect this project.' --policy configs/policy.readonly.json --url http://127.0.0.1:8000/v1 --model your-served-model
The external server must support JSON-schema responses. A remote hostname additionally requires --allow-network; prompts/files may then leave the device. Set NEXORA_API_KEY only when the chosen server requires authentication. The local development server below deliberately rejects constrained-output requests because it does not implement grammar-constrained decoding.
Local streaming endpoint
Set a random local token without committing it:
$env:NEXORA_LOCAL_TOKEN=[guid]::NewGuid().ToString('N')
python -m nexora.cli serve --model .cache/Qwen3.5-0.8B --port 8765
Use POST http://127.0.0.1:8765/v1/chat/completions with Authorization: Bearer <your token>, a messages array and optionally "stream": true. SSE returns text deltas and [DONE]. Only one model request runs at a time; excess requests return 503. /health reports availability. Binding is loopback-only, browser Origin requests are rejected, input is capped, and prompts are not logged. This development server is a subset of chat completion semantics: native tool calls, JSON constraints, per-request sampling controls, production load balancing and internet deployment are not supported. Stop with Ctrl+C. No server is left running by the build.
Voice and private data
pip install -e '.[voice]' enables optional file ASR and OS speech adapters. Model downloads and microphone/speaker behavior have not been validated on this host. VoiceSession accepts async reply/speak/stop callbacks; cancellation mechanics are tested with controlled callbacks. It does not claim full-duplex audio or automatic microphone permission.
SQLite memory and failure records belong under private/, excluded from publication. Failure capture requires explicit consent; promotion to a training candidate requires staged evidence and provenance approval. Regex redaction is not a complete PII detector. No telemetry endpoint is configured. Hugging Face operations upload only the curated release stage, never the working cache/private directories.
Publishing and reproducibility
scripts/package_release.py creates a fresh allowlisted .release/stage-<id> with a SHA-256 manifest and source revision. scripts/verify_release.py verifies local or downloaded manifests. The package excludes upstream caches, private databases, credentials and bytecode. Code license and upstream model attribution are distinct. The generated release manifest plus immutable Hub commit identifies the exact published snapshot. Rerun tests whenever implementation changes; model training does not need rerunning for documentation-only edits.