NeuroShift Engine

NeuroShift Engine is a local-first, provider-neutral AI runtime. The current local CLI runs a bounded autonomous repository loop in observe mode by default. Explicit workspace permission adds guarded file mutation and supervised command.run/test.run; the separate M3 exec path still runs one explicitly supplied argv command. Host command execution is not a sandbox.

The repository also contains the existing FastAPI service and Next.js application. FastAPI remains a compatible adapter: its JSON and SSE model dispatch pass through the core runtime seam without changing the hosted API contract.

Local Quick Start

Requires Python 3.11 or newer. Appwrite, Redis, Node.js, and the web application are not required to run the local CLI.

python -m venv .venv
./.venv/bin/python -m pip install -e .
export NEUROSHIFT_MODEL=openai/gpt-4o-mini
export OPENAI_API_KEY=your-key
./.venv/bin/neuroshift run --workspace . "Summarize this repository"

To permit a bounded edit-and-test trajectory:

./.venv/bin/neuroshift run --permission workspace --max-turns 8 --timeout 120 \
  --workspace . "Fix the failing focused test, run it, and summarize the diff"

Workspace changes are preserved by default. A successful recognized test.run must follow the latest workspace mutation for a successful outcome; final command-created Git changes without a successful test are incomplete.

The provider adapter uses LiteLLM, so choose a LiteLLM model identifier and export the credential variables required by that provider. NeuroShift's CLI does not automatically load .env; export variables in the process environment or use your own environment manager.

For a deterministic smoke test with no provider network request:

NEUROSHIFT_ENABLE_STUB_PROVIDER=true \
  ./.venv/bin/neuroshift run --provider stub --workspace . "Smoke test"

The real-provider command sends the task and selected repository excerpts to the configured provider. Sensitive files, ignored directories, binary files, symlinks, and paths outside the workspace are excluded by the local reader, but review provider policy before sending source code.

To run one reviewed development command:

./.venv/bin/neuroshift exec --permission workspace --workspace . -- pytest -q

This executes on the host with a reduced environment, command deny rules, bounded output, and process-group cleanup. It is not a sandbox and does not prevent filesystem or network access.

See Autonomous Runtime, Local Runtime, Local Execution Security, Core Architecture, and CLI Reference.

Capability Status

Stable / Compatible

• Existing authenticated FastAPI JSON and SSE chat surfaces
• FastAPI legacy dispatch compatibility through invoke_legacy_json and invoke_legacy_stream

"Stable" here identifies compatibility targets in this repository, not a production-readiness or semantic-versioning guarantee.

Experimental

• app/core: typed task, event, provider, context, tool, and persistence boundaries
• app/local: bounded workspace reads, Git status/diff, descriptor-backed file mutations with task-scoped rollback, and supervised argv execution
• neuroshift run: bounded provider/tool continuation with default observe tools and explicit workspace mutation plus command/test tools
• neuroshift exec: one explicitly authorized, supervised host command
• LiteLLM fragmented structured-call assembly, strict finish validation, capability/schema/permission checks, task-local approvals, and runtime-owned outcomes/evidence
• Deterministic fake-provider E2E coverage of a real inspect/edit/test/diff M3 tool trajectory without provider network access

Experimental interfaces may change. The local CLI does not expose shell-string execution, raw sandbox or browser/desktop access, sudo, or dedicated Git stage/commit/push tools. The argv executor is not host containment.

Hosted-Only

• Authentication, account-scoped conversations, feedback, regeneration, and daily usage
• Server-side routing, API-key management, billing, uploads, semantic cache, retrieval, and administrative APIs
• Next.js chat, dashboard, playground, settings, and API documentation

Full-Stack Service

Running the complete hosted-style stack requires Python 3.11+, Node.js 20+, Redis, an Appwrite project, and credentials for enabled integrations.

cp .env.example .env
python -m venv .venv
./.venv/bin/python -m pip install -r requirements-dev.txt
./.venv/bin/uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

In another terminal:

cd frontend
cp .env.example .env.local
npm ci
npm run dev

Open http://localhost:3000; API health is at http://localhost:8000/health. All NEXT_PUBLIC_* values are browser-visible; never place provider or server credentials in frontend configuration.

Verification

./.venv/bin/python -m pytest tests
cd frontend
npm run lint
npx tsc --noEmit
npm run build

Contributing, Security, and License

See CONTRIBUTING.md for development expectations. Report vulnerabilities through SECURITY.md, not a public issue. NeuroShift Engine is available under the MIT License.