open-context-engine 0.1.2 → 0.1.4

package/src/retrieval/languages/python_calls.py

@@ -0,0 +1,188 @@
+"""Conservative lexical import/call resolution; never infer dynamic receivers."""
+import ast
+
+
+def import_bindings(node, module, package):
+    if isinstance(node, ast.Import):
+        return {a.asname or a.name.split('.')[0]: a.name if a.asname else a.name.split('.')[0]
+                for a in node.names}
+    prefix = node.module or ''
+    if node.level:
+        parts = package.split('.') if package else []
+        if node.level > len(parts):
+            return {}
+        prefix = '.'.join(parts[:len(parts) - node.level + 1] + ([prefix] if prefix else []))
+    return {a.asname or a.name: '.'.join(filter(None, [prefix, a.name]))
+            for a in node.names if a.name != '*'}
+
+
+class Bindings(ast.NodeVisitor):
+    def __init__(self):
+        self.names = set()
+
+    def visit_Name(self, node):
+        if isinstance(node.ctx, (ast.Store, ast.Del)):
+            self.names.add(node.id)
+
+    def visit_Import(self, node):
+        self.names.update(a.asname or a.name.split('.')[0] for a in node.names)
+
+    def visit_ImportFrom(self, node):
+        self.names.update(a.asname or a.name for a in node.names)
+
+    def visit_FunctionDef(self, node):
+        self.names.add(node.name)
+
+    visit_AsyncFunctionDef = visit_FunctionDef
+    visit_ClassDef = visit_FunctionDef
+    def visit_Lambda(self, node):
+        pass
+
+    def visit_ExceptHandler(self, node):
+        if node.name:
+            self.names.add(node.name)
+        self.generic_visit(node)
+
+
+def bound(body):
+    visitor = Bindings()
+    for node in body:
+        visitor.visit(node)
+    return visitor.names
+
+
+def resolved_links(tree, module, package):
+    """Return calls with source positions and scoped, qualified targets.
+
+    Imports under uncertain control flow are not assumed to have executed.
+    Function-local names shadow outer bindings even before their assignment.
+    """
+    calls, references = [], []
+    globals_ = {}
+    for node in tree.body:
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            globals_.update(import_bindings(node, module, package))
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            globals_[node.name] = module + '.' + node.name
+    # A module-level reassignment makes the runtime binding indeterminate.
+    for node in tree.body:
+        if not isinstance(node, (ast.Import, ast.ImportFrom, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            for name in bound([node]):
+                globals_.pop(name, None)
+
+    def expression(node, env):
+        if node is None:
+            return
+        if isinstance(node, ast.Lambda):
+            local = env.copy()
+            for arg in node.args.posonlyargs + node.args.args + node.args.kwonlyargs:
+                local.pop(arg.arg, None)
+            for arg in (node.args.vararg, node.args.kwarg):
+                if arg:
+                    local.pop(arg.arg, None)
+            expression(node.body, local)
+            return
+        if isinstance(node, (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)):
+            local = env.copy()
+            for gen in node.generators:
+                expression(gen.iter, local)
+                for name in bound([gen.target]):
+                    local.pop(name, None)
+                for condition in gen.ifs:
+                    expression(condition, local)
+            for field in ('elt', 'key', 'value'):
+                expression(getattr(node, field, None), local)
+            return
+        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load) and node.id in env:
+            references.append((node.lineno, env[node.id]))
+        if isinstance(node, ast.Call):
+            pieces = []
+            head = node.func
+            while isinstance(head, ast.Attribute):
+                pieces.insert(0, head.attr)
+                head = head.value
+            if isinstance(head, ast.Name) and head.id in env:
+                calls.append((node.lineno, '.'.join([env[head.id]] + pieces)))
+        for child in ast.iter_child_nodes(node):
+            expression(child, env)
+
+    def statements(body, env, owner=None, prefix='', class_closure=None):
+        for node in body:
+            if isinstance(node, (ast.Import, ast.ImportFrom)):
+                env.update(import_bindings(node, module, package))
+            elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                for item in node.decorator_list + node.args.defaults + [d for d in node.args.kw_defaults if d]:
+                    expression(item, env)
+                local = (class_closure if owner and class_closure is not None else env).copy()
+                for name in bound(node.body):
+                    local.pop(name, None)
+                for arg in node.args.posonlyargs + node.args.args + node.args.kwonlyargs:
+                    local.pop(arg.arg, None)
+                for arg in (node.args.vararg, node.args.kwarg):
+                    if arg:
+                        local.pop(arg.arg, None)
+                args = node.args.posonlyargs + node.args.args
+                if owner and args and args[0].arg in {'self', 'cls'} and args[0].arg not in bound(node.body):
+                    local[args[0].arg] = owner
+                statements(node.body, local, prefix=prefix + node.name + '.')
+                env[node.name] = module + '.' + prefix + node.name
+            elif isinstance(node, ast.ClassDef):
+                for item in node.decorator_list + node.bases:
+                    expression(item, env)
+                name = module + '.' + prefix + node.name
+                # Methods close over the containing function/module, not class locals.
+                statements(node.body, env.copy(), owner=name, prefix=prefix + node.name + '.', class_closure=env.copy())
+                env[node.name] = name
+            elif isinstance(node, (ast.If, ast.For, ast.AsyncFor, ast.While, ast.With, ast.AsyncWith, ast.Try, ast.TryStar, ast.Match)):
+                # Visit each branch in an isolated scope; invalidate any names
+                # it could write, so uncertain imports cannot leak past it.
+                changed = bound([node])
+                branch_env = {k: v for k, v in env.items() if k not in changed}
+                for field, value in ast.iter_fields(node):
+                    if field in {'body', 'orelse', 'finalbody'}:
+                        statements(value, branch_env.copy(), owner, prefix, class_closure)
+                    elif field == 'handlers':
+                        for handler in value:
+                            statements(handler.body, branch_env.copy(), owner, prefix, class_closure)
+                    elif field == 'cases':
+                        for case in value:
+                            expression(case.guard, branch_env)
+                            statements(case.body, branch_env.copy(), owner, prefix, class_closure)
+                    elif isinstance(value, ast.AST):
+                        expression(value, env)
+                    elif isinstance(value, list):
+                        for item in value:
+                            if isinstance(item, ast.AST):
+                                expression(item, env)
+                for name in changed:
+                    env.pop(name, None)
+            else:
+                expression(node, env)
+                for name in bound([node]):
+                    env.pop(name, None)
+    statements(tree.body, globals_.copy())
+    return {'calls': calls, 'references_value': references}
+
+
+def symbol_resolver(modules, symbols):
+    """Allow source-root prefixes only when a module suffix is unambiguous."""
+    suffixes = {}
+    for module in modules:
+        parts = module.split('.')
+        for i in range(len(parts)):
+            suffixes.setdefault('.'.join(parts[i:]), set()).add(module)
+
+    def resolve(target):
+        if target in symbols:
+            return symbols[target]
+        parts = target.split('.')
+        for split in range(len(parts) - 1, 0, -1):
+            name = '.'.join(parts[:split])
+            matches = {name} if name in modules else suffixes.get(name, set())
+            if len(matches) == 1:
+                qualified = next(iter(matches)) + '.' + '.'.join(parts[split:])
+                return symbols.get(qualified, [])
+            if matches:
+                return []
+        return []
+    return resolve

package/src/retrieval/languages/schema.py

@@ -3,9 +3,16 @@ from dataclasses import dataclass
 import math
 from typing import TypedDict
 
-SCHEMA_VERSION = 'source-units-v2'
+SCHEMA_VERSION = 'source-units-v3'
 RELATION_KINDS = frozenset({'calls', 'member_of', 'inherits', 'implements',
-                            'same_symbol', 'imports', 'references_type'})
+                            'same_symbol', 'imports', 'references_type', 'references_value'})
+
+
+class SourceSyntaxError(ValueError):
+    """File-local syntax diagnostics, distinct from adapter or validation failures."""
+    def __init__(self, diagnostics):
+        super().__init__('Source syntax errors')
+        self.diagnostics = diagnostics
 
 
 @dataclass(frozen=True)

package/src/retrieval/languages/typescript.mjs

@@ -1,7 +1,8 @@
 /** Parse and bind only the frozen source set. Never emit, execute, or load repo plugins. */
 import ts from 'typescript';
-import { readFileSync } from 'node:fs';
+import { readFileSync, existsSync, realpathSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const COMPILER_VERSION = '5.9.3';
 if (ts.version !== COMPILER_VERSION) throw new Error(`Expected TypeScript ${COMPILER_VERSION}; run npm ci`);
@@ -44,10 +45,16 @@ export function extract(files, maxLines = 65, settings = {}) {
   const program = ts.createProgram([...texts.keys()], options, host);
   const errors = program.getSyntacticDiagnostics();
   if (errors.length) {
-    throw new Error(errors.slice(0, 5).map(d => {
-      const line = d.file.getLineAndCharacterOfPosition(d.start ?? 0).line + 1;
-      return `${path.posix.relative(ROOT, d.file.fileName)}:${line}: ${ts.flattenDiagnosticMessageText(d.messageText, ' ')}`;
-    }).join('\n'));
+    if (errors.some(d => !d.file)) throw new Error('TypeScript syntax diagnostic is missing a source file');
+    const diagnostics = new Map();
+    for (const d of errors) {
+      const name = path.posix.relative(ROOT, d.file.fileName);
+      const position = d.file.getLineAndCharacterOfPosition(d.start ?? 0);
+      if (!diagnostics.has(name)) diagnostics.set(name, {path:name,
+        language:/\.(?:jsx?|mjs|cjs)$/i.test(name) ? 'javascript' : 'typescript',
+        errorType:'SyntaxError', line:position.line + 1, column:position.character + 1});
+    }
+    return {compilerVersion:ts.version, units:[], syntaxErrors:[...diagnostics.values()]};
   }
   const checker = program.getTypeChecker();
   const units = [], records = new Map(), nodeEntries = new Map();
@@ -223,7 +230,8 @@ export function extract(files, maxLines = 65, settings = {}) {
   return { compilerVersion: ts.version, units };
 }
 
-if (process.argv[1] && new URL(import.meta.url).pathname === path.resolve(process.argv[1])) {
+if (process.argv[1] && existsSync(process.argv[1])
+    && realpathSync.native(fileURLToPath(import.meta.url)) === realpathSync.native(process.argv[1])) {
   try {
     const input = JSON.parse(readFileSync(0, 'utf8'));
     process.stdout.write(JSON.stringify(extract(input.files, input.maxLines, input.options)));

package/src/retrieval/languages/typescript.py

@@ -2,6 +2,7 @@
 import json
 from pathlib import Path
 import subprocess
+from .schema import SourceSyntaxError
 
 COMPILER_VERSION = '5.9.3'
 
@@ -11,7 +12,7 @@ def extract(sources, max_lines=65, options=None):
                'maxLines': max_lines, 'options': options or {}}
     try:
         result = subprocess.run(['node', str(Path(__file__).with_suffix('.mjs'))],
-                                input=json.dumps(payload), text=True, capture_output=True,
+                                input=json.dumps(payload), encoding='utf-8', capture_output=True,
                                 timeout=120, check=False)
     except FileNotFoundError as error:
         raise RuntimeError('TypeScript indexing requires Node.js and npm ci') from error
@@ -20,4 +21,6 @@ def extract(sources, max_lines=65, options=None):
     output = json.loads(result.stdout)
     if output['compilerVersion'] != COMPILER_VERSION:
         raise ValueError('Unexpected TypeScript compiler version; run npm ci')
+    if output.get('syntaxErrors'):
+        raise SourceSyntaxError(output['syntaxErrors'])
     return output['units']

package/src/retrieval/live.py

@@ -2,7 +2,6 @@
 from collections import Counter
 from contextlib import closing
 from dataclasses import dataclass
-import fcntl
 import hashlib
 import json
 import os
@@ -18,7 +17,8 @@ import numpy as np
 from engine import document, post
 from languages import adapter_manifest, source_units
 from languages.files import discover_snapshot
-from routed import RoutedEngine
+from evidence import EvidenceEngine
+from writer_lock import acquire_writer_lock
 
 
 def digest(value):
@@ -42,7 +42,7 @@ class Generation:
 
 
 class LiveIndex:
-    def __init__(self, config, *, embed=post, engine_factory=RoutedEngine):
+    def __init__(self, config, *, embed=post, engine_factory=EvidenceEngine):
         self.config = config
         self.root = Path(config['root']).resolve()
         self.state = Path(config['state']).resolve()
@@ -64,6 +64,9 @@ class LiveIndex:
         self.dimensions = self.embedding['dimensions']
         if type(self.dimensions) is not int or not 1 <= self.dimensions <= 65536:
             raise ValueError('Invalid embedding dimensions')
+        self.batch_size = config.get('embeddingBatchSize', 64)
+        if type(self.batch_size) is not int or not 1 <= self.batch_size <= 64:
+            raise ValueError('Embedding batch size must be an integer from 1 to 64')
         self.embed, self.engine_factory = embed, engine_factory
         self.condition = threading.Condition()
         self.stop_event = threading.Event()
@@ -72,12 +75,7 @@ class LiveIndex:
         self.phase = 'starting'
         self.parse_cache = {}
         self.state.mkdir(parents=True, exist_ok=True, mode=0o700)
-        self.lock_file = (self.state/'writer.lock').open('a')
-        try:
-            fcntl.flock(self.lock_file, fcntl.LOCK_EX | fcntl.LOCK_NB)
-        except OSError:
-            self.lock_file.close()
-            raise ValueError('This index directory already has a running writer') from None
+        self.lock_file = acquire_writer_lock(self.state/'writer.lock')
         self.thread = threading.Thread(target=self._run, name='repository-index', daemon=True)
 
     def scan(self):
@@ -169,7 +167,9 @@ class LiveIndex:
 
     def _build(self, snapshot, identity):
         start = time.monotonic()
-        units = source_units(self.root, snapshot['files'], language_options=self.options, cache=self.parse_cache)
+        report = {}
+        units = source_units(self.root, snapshot['files'], language_options=self.options,
+                             cache=self.parse_cache, report=report)
         documents = [document(unit) for unit in units]
         keys = [digest([self.embedding, text]) for text in documents]
         vectors, missing = {}, {}
@@ -184,10 +184,10 @@ class LiveIndex:
                         continue
                 missing[key] = text
             entries = list(missing.items())
-            for offset in range(0, len(entries), 64):
+            for offset in range(0, len(entries), self.batch_size):
                 if self.stop_event.is_set():
                     raise SourceChanged()
-                batch = entries[offset:offset+64]
+                batch = entries[offset:offset+self.batch_size]
                 result = self.embed(self.config['embeddingUrl']+'/embeddings',
                     {'model': self.embedding['model'], 'input': [text for _, text in batch]},
                     self.config.get('embeddingKey', 'local-only'), timeout=60)
@@ -212,6 +212,7 @@ class LiveIndex:
                 'changedFiles': sum(previous.get(path) != sha for path, sha in now.items()),
                 'deletedFiles': len(previous.keys() - now.keys()), 'embedding': self.embedding,
                 'languageUnits': dict(Counter(unit['language'] for unit in units)),
+                'degradedFiles': report['degradedFiles'], 'parseDiagnostics': report['parseDiagnostics'],
                 'indexingMs': round((time.monotonic()-start)*1000), 'completedAt': time.time()}
         folder = self.state/('generation-'+uuid.uuid4().hex)
         folder.mkdir(mode=0o700)

package/src/retrieval/planning.py

@@ -0,0 +1,15 @@
+"""Deterministic behavior facets; every facet retains its full query context in retrieval."""
+import re
+
+
+def plan_query(query):
+    # Keep conditions in the intent, but do not spend a facet on a condition
+    # such as "when a user reopens a chat" without its requested behavior.
+    parts = [part.strip() for part in re.split(
+        r'[:：;；，]|,\s+(?=how|which|why|where|what)|\s+and\s+(?=how|which|why|where|what|preserve|restore|validate|enforce|handle|load|save|reject|filter|check|merge|retain|stop)',
+        query, flags=re.I) if len(part.strip()) > 7]
+    actionable = [part for part in parts if not re.match(r'^(when|if|after|before|unless|given)\b', part, re.I)
+                  and not (part.endswith('时') and not re.search(r'如何|怎么|哪里|怎样', part))]
+    facets = actionable if 1 < len(actionable) <= 4 else [query]
+    return {'intent': query, 'facets': [{'question': part, 'terms': re.findall(r'[A-Za-z][A-Za-z0-9_]*', part)}
+                                      for part in facets]}

package/src/retrieval/reranker.py

@@ -33,8 +33,8 @@ def checked_rows(data, count):
 
 def rerank_pairs(config, queries, documents, pairs, post):
     api = config.get('api', 'rerank')
-    if api not in ('rerank', 'rerank-batch'):
-        raise ValueError('Rerank API must be rerank or rerank-batch')
+    if api not in ('rerank', 'rerank-batch', 'dashscope'):
+        raise ValueError('Rerank API must be rerank, rerank-batch or dashscope')
     concurrency = bounded_integer(config.get('concurrency', 2), 'Rerank concurrency', 8)
     limit = bounded_integer(config.get('maxDocuments', 128), 'Rerank document limit', 1024)
     for q, d in pairs:
@@ -42,7 +42,8 @@ def rerank_pairs(config, queries, documents, pairs, post):
             raise ValueError('Invalid requested rerank pair')
     if not pairs:
         return {'results': [], 'meta': {'request_count': 0}}
-    url = config['baseUrl'].rstrip('/') + '/' + api
+    path = 'services/rerank/text-rerank/text-rerank' if api == 'dashscope' else api
+    url = config['baseUrl'].rstrip('/') + '/' + path
     if api == 'rerank-batch':
         data = post(url, {'model': config['model'], 'queries': queries,
                          'documents': documents, 'pairs': pairs}, config['apiKey'])
@@ -61,9 +62,14 @@ def rerank_pairs(config, queries, documents, pairs, post):
 
     def request(job):
         q, ids = job
-        data = post(url, {'model': config['model'], 'query': queries[q],
-                         'documents': [documents[d] for d in ids], 'top_n': len(ids)}, config['apiKey'])
-        rows = checked_rows(data, len(ids))
+        inputs = {'query': queries[q], 'documents': [documents[d] for d in ids]}
+        body = ({'model': config['model'], 'input': inputs, 'parameters': {'top_n': len(ids)}}
+                if api == 'dashscope' else {'model': config['model'], **inputs, 'top_n': len(ids)})
+        data = post(url, body, config['apiKey'])
+        rows = checked_rows(data.get('output') if api == 'dashscope' and isinstance(data, dict) else data, len(ids))
+        if api == 'dashscope':
+            usage = data.get('usage', {})
+            data = {**data, 'usage': {'input_tokens': usage.get('total_tokens')} if isinstance(usage, dict) else {}}
         return {(q, ids[row['index']]): row['relevance_score'] for row in rows}, data
 
     # Fail the whole wave on any error; never silently drop a query or switch API.

package/src/retrieval/shared_worker.py

@@ -0,0 +1,115 @@
+"""Discovery and expiring client leases for a single locked index writer."""
+import json
+import os
+from pathlib import Path
+import secrets
+import re
+import subprocess
+import sys
+import threading
+import time
+
+PROTOCOL = 1
+
+
+def restrict_permissions(path):
+    if sys.platform == 'win32':
+        # os.open(mode=0o600) does not set a Windows DACL. Resolve the current
+        # user's SID (independent of localized account names) and remove inheritance.
+        result = subprocess.run(['whoami', '/user', '/fo', 'csv', '/nh'],
+                                capture_output=True, check=True, timeout=5)
+        match = re.search(rb'S-1-[0-9-]+', result.stdout)
+        if not match:
+            raise PermissionError('Cannot determine current Windows user SID')
+        sid = match.group().decode('ascii')
+        subprocess.run(['icacls', str(path), '/inheritance:r', '/grant:r', '*' + sid + ':F'],
+                       capture_output=True, check=True, timeout=5)
+
+
+class SharedWorker:
+    def __init__(self, config):
+        options = config['shared']
+        self.path = Path(config['state']) / 'worker.json'
+        self.instance = secrets.token_hex(24)
+        self.fingerprint = options['fingerprint']
+        self.key = config['serviceKey']
+        self.ttl = options.get('leaseSeconds', 15)
+        self.idle = options.get('idleSeconds', 30)
+        self.leases = {}
+        self.active = 0
+        self.empty_since = time.monotonic()
+        self.stopping = False
+        self.lock = threading.Lock()
+        self.finished = threading.Event()
+
+    def publish(self, port):
+        # Called only by the writer-lock holder, after HTTP bind succeeds.
+        self.record = {'protocol': PROTOCOL, 'instanceId': self.instance,
+                       'pid': os.getpid(), 'port': port, 'apiKey': self.key}
+        temporary = self.path.with_name('worker-' + self.instance + '.tmp')
+        try:
+            with os.fdopen(os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), 'w') as file:
+                restrict_permissions(temporary)
+                json.dump(self.record, file)
+            os.replace(temporary, self.path)
+        finally:
+            temporary.unlink(missing_ok=True)
+
+    def lease(self, body, release=False):
+        with self.lock:
+            if body.get('instanceId') != self.instance:
+                return 409, {'error': 'Worker instance changed', 'code': 'INSTANCE_CHANGED'}
+            if not secrets.compare_digest(str(body.get('fingerprint', '')), self.fingerprint):
+                return 409, {'error': 'This index is used by a worker with incompatible configuration or runtime. '
+                             'Close its clients before changing configuration, or use a separate --state directory.',
+                             'code': 'CONFIG_MISMATCH'}
+            identifier = body.get('leaseId')
+            if not isinstance(identifier, str) or not 1 <= len(identifier) <= 128:
+                return 422, {'error': 'Invalid lease identifier'}
+            if self.stopping:
+                return 503, {'error': 'Worker is stopping'}
+            if release:
+                self.leases.pop(identifier, None)
+            else:
+                self.leases[identifier] = time.monotonic() + self.ttl
+            self.empty_since = time.monotonic()
+            return 200, {'instanceId': self.instance, 'pid': os.getpid(), 'leaseSeconds': self.ttl}
+
+    def enter(self):
+        with self.lock:
+            if self.stopping:
+                return False
+            self.active += 1
+            return True
+
+    def leave(self):
+        with self.lock:
+            self.active -= 1
+            self.empty_since = time.monotonic()
+
+    def should_stop(self):
+        with self.lock:
+            now = time.monotonic()
+            self.leases = {key: until for key, until in self.leases.items() if until > now}
+            if self.leases or self.active:
+                self.empty_since = now
+            elif now - self.empty_since >= self.idle:
+                self.stopping = True
+            return self.stopping
+
+    def monitor(self, server):
+        def run():
+            while not self.finished.wait(min(1, self.idle / 2)):
+                if self.should_stop():
+                    server.shutdown()
+                    return
+        threading.Thread(target=run, name='worker-leases', daemon=True).start()
+
+    def close(self):
+        self.finished.set()
+        # Cleanup precedes releasing the writer lock; never unlink a successor's record.
+        try:
+            if json.loads(self.path.read_text()).get('instanceId') == self.instance:
+                self.path.unlink()
+        except (FileNotFoundError, ValueError):
+            pass

package/src/retrieval/writer_lock.py

@@ -0,0 +1,29 @@
+"""Nonblocking process lock, released when its file handle is closed."""
+import sys
+
+if sys.platform == 'win32':
+    import msvcrt
+
+    def lock(file):
+        # Every writer locks the same byte, including when the file is empty.
+        file.seek(0)
+        msvcrt.locking(file.fileno(), msvcrt.LK_NBLCK, 1)
+else:
+    import fcntl
+
+    def lock(file):
+        fcntl.flock(file, fcntl.LOCK_EX | fcntl.LOCK_NB)
+
+
+class WriterBusy(ValueError):
+    pass
+
+
+def acquire_writer_lock(path):
+    file = path.open('a+b')
+    try:
+        lock(file)
+    except OSError:
+        file.close()
+        raise WriterBusy(f'This index directory already has a running writer: {path}') from None
+    return file

package/src/runtime.mjs

@@ -6,6 +6,12 @@ import { createHash } from 'node:crypto';
 import { configDirectory, projectRoot } from './config.mjs';
 
 const exec = promisify(execFile);
+export function defaultPython(platform = process.platform) {
+  return platform === 'win32' ? 'python' : 'python3';
+}
+export function venvPython(directory, platform = process.platform) {
+  return platform === 'win32' ? join(directory,'Scripts','python.exe') : join(directory,'bin','python');
+}
 export async function run(command, args, options = {}) {
   try {return await exec(command,args,{timeout:600000,maxBuffer:4*1024*1024,...options});}
   catch (error) {
@@ -21,7 +27,8 @@ export async function verifyPython(python, environment = process.env, execute =
   return (await execute(python,['-c',probe],{env:environment,timeout:120000})).stdout.trim();
 }
 
-export async function ensureRuntime(environment, {python = 'python3', execute = run, log = () => {}} = {}) {
+export async function ensureRuntime(environment, {platform = process.platform,
+  python = defaultPython(platform), execute = run, log = () => {}} = {}) {
   const runtimes = join(configDirectory(environment),'runtimes');
   const requirements = await readFile(join(projectRoot,'requirements.txt'));
   const fingerprint = createHash('sha256').update(requirements).digest('hex');
@@ -43,7 +50,7 @@ export async function ensureRuntime(environment, {python = 'python3', execute =
   await mkdir(runtimes,{recursive:true,mode:0o700});
   // Virtual environments cannot be relocated. Each installation is built in its final directory.
   const directory = await mkdtemp(join(runtimes,'python-'));
-  const executable = join(directory,'bin','python');
+  const executable = venvPython(directory,platform);
   const env = {...environment,TIKTOKEN_CACHE_DIR:join(directory,'tokenizer')};
   try {
     log('Creating an isolated Python environment...');