fxbx 0.7.0__py3-none-any.whl

fxbex/__init__.py

@@ -0,0 +1,16 @@
+"""Independent FXBEX package builder and installed-adapter runtime."""
+__version__ = "0.7.0"
+
+from .llm import LLM
+from .model import Model, YOLO, ObjectDetection, ImageGeneration
+__all__ = ['Model', 'LLM', 'YOLO', 'ObjectDetection', 'ImageGeneration','hug','describe','example_inputs','as_torch']
+
+from .schema import describe, example_inputs
+
+from .hug import hug
+
+
+def as_torch(package, *, execution_policy='npu_only', inference_only=True, output_device='cpu'):
+    """Opt-in immutable nn.Module wrapper; importing FXBEX alone does not import torch."""
+    from .torch_api import CompiledModule
+    return CompiledModule(package,execution_policy=execution_policy,inference_only=inference_only,output_device=output_device)

fxbex/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

fxbex/buildbundle.py

@@ -0,0 +1,54 @@
+"""TPLMachine delivery receipt bound to all execution-relevant source contents."""
+import hashlib
+import json
+from pathlib import Path
+from .package import PackageError
+
+NAME='build_bundle.json'
+def file_sha(path):
+    h=hashlib.sha256()
+    with path.open('rb') as stream:
+        for block in iter(lambda:stream.read(1024*1024),b''):h.update(block)
+    return h.hexdigest()
+def sha(data):return hashlib.sha256(data).hexdigest()
+def semantic_manifest(manifest):
+    return {k:manifest.get(k) for k in ('model','runtime','compatibility','io_contract','memory','state_contract')}
+def validate(root,manifest):
+    root=Path(root);path=root/NAME
+    if not path.exists():return None
+    if path.stat().st_size>16*1024**2:raise PackageError('Oversized BuildBundle')
+    bundle=json.loads(path.read_text());files=bundle.get('content',{})
+    if bundle.get('schema')!='tplmachine.build-bundle.v1' or not files:
+        raise PackageError('Invalid BuildBundle')
+    canonical=lambda x:json.dumps(x,sort_keys=True,separators=(',',':'),allow_nan=False).encode()
+    if sha(canonical(semantic_manifest(manifest)))!=bundle.get('manifest_semantics_sha256'):
+        raise PackageError('BuildBundle manifest semantics changed')
+    actual={str(p.relative_to(root)):file_sha(p) for p in root.rglob('*') if p.is_file() and str(p.relative_to(root)) not in (NAME,'manifest.json')}
+    if actual!=files:raise PackageError('BuildBundle content changed or missing files')
+    acceptance=bundle.get('acceptance',{})
+    expected=sha(canonical({'files':files,'manifest':bundle['manifest_semantics_sha256']}))
+    if bundle.get('content_id')!=expected or acceptance.get('content_id')!=expected:
+        raise PackageError('BuildBundle acceptance belongs to different contents')
+    if (bundle.get('status')!='validated' or acceptance.get('fresh_process_reload') is not True
+            or acceptance.get('numerical_passed') is not True or acceptance.get('completion_confirmed') is not True
+            or acceptance.get('state_validation') not in ('passed','not_applicable')
+            or type(acceptance.get('npu_tasks')) is not int or acceptance['npu_tasks']<1
+            or any(type(acceptance.get(k)) is not int or acceptance[k]!=0 for k in ('cpu_routes','unknown_graphs','compiler_calls'))):
+        raise PackageError('BuildBundle has not passed independent execution acceptance')
+    stateful=manifest.get('io_contract',{}).get('method') in ('chat','generate') or manifest.get('state_contract') not in (None,{}, {'kind':'stateless'})
+    if stateful and acceptance['state_validation']!='passed':
+        raise PackageError('BuildBundle stateful model requires state validation')
+    return {'content_id':expected,'status':'validated','current_request_npu_execution':'unknown'}
+
+
+def prepare_source(root):
+    """Freeze the same public metadata that package.build will generate before binding."""
+    root=Path(root);index=json.loads((root/'weights_index.json').read_text())
+    if any('external_path' in w for w in index['weights']):
+        raise PackageError('BuildBundle requires already internalized weights')
+    (root/'weights_index.json').write_bytes(json.dumps(index,sort_keys=True).encode())
+    manifest=json.loads((root/'manifest.json').read_text())
+    if manifest['runtime']['adapter']=='runnable_dag':
+        from .memory import analyze
+        memory=analyze(root)
+        (root/'memory_plan.json').write_bytes(json.dumps(memory,sort_keys=True).encode())

fxbex/bundled.py

@@ -0,0 +1,45 @@
+"""Explicit trusted Python runtime bundles; not a sandbox for untrusted packages."""
+from contextlib import contextmanager
+import importlib
+import re
+import sys
+from .package import PackageError
+
+
+def specification(manifest):
+    spec=manifest['runtime'].get('bundled_python')
+    if spec is None:return None
+    if not isinstance(spec,dict) or spec.get('root')!='python':raise PackageError('Expected bundled_python root=python')
+    entry=spec.get('entrypoint','')
+    if not isinstance(entry,str) or not re.fullmatch(r'[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*:[A-Za-z_]\w*',entry):
+        raise PackageError('Invalid bundled adapter entrypoint')
+    packages=spec.get('packages')
+    if not isinstance(packages,list) or not packages or any(not isinstance(p,str) or not re.fullmatch(r'[A-Za-z_]\w*',p) for p in packages):
+        raise PackageError('Invalid bundled top-level packages')
+    if len(set(packages))!=len(packages) or entry.split('.')[0].split(':')[0] not in packages or 'fxbex' in packages:
+        raise PackageError('Invalid bundled package ownership')
+    for p in packages:
+        if f'python/{p}/__init__.py' not in manifest['files']:raise PackageError(f'Missing bundled package {p}')
+    module=entry.split(':')[0].replace('.','/')
+    if f'python/{module}.py' not in manifest['files']:raise PackageError('Missing bundled entrypoint source')
+    return spec
+
+
+@contextmanager
+def activate(root,manifest):
+    spec=specification(manifest)
+    if spec is None:
+        yield None;return
+    names=spec['packages']
+    def owned(n):return any(n==p or n.startswith(p+'.') for p in names)
+    if any(owned(n) for n in sys.modules):
+        raise PackageError('Bundled runtime conflicts with imported modules; use a fresh FXBEX worker')
+    directory=str(root/'python');sys.path.insert(0,directory)
+    try:
+        module,attribute=spec['entrypoint'].split(':')
+        yield getattr(importlib.import_module(module),attribute)
+    finally:
+        if directory in sys.path:sys.path.remove(directory)
+        for n in list(sys.modules):
+            if owned(n):del sys.modules[n]
+        importlib.invalidate_caches()

fxbex/cli.py

@@ -0,0 +1,245 @@
+"""CLI for local FXB_EX packages; SDK is imported only for runtime operations."""
+import argparse
+import json
+from pathlib import Path
+import sys
+import threading
+import time
+from .package import build, inspect
+from .validation import validate
+
+
+def _runtime_call(callback, log_path, verbose=False):
+    """Keep framework diagnostics separate from answers and JSON results."""
+    if verbose:return callback()
+    import contextlib
+    with log_path.open('a') as log, contextlib.redirect_stdout(log), contextlib.redirect_stderr(log):
+        return callback()
+
+
+def _load_with_progress(callback, stream, interval=5):
+    """Report elapsed time without inventing a completion percentage."""
+    stopped = threading.Event()
+    started = time.monotonic()
+    interactive = stream.isatty()
+    displayed = False
+    def report():
+        nonlocal displayed
+        while not stopped.wait(interval):
+            message = f'Model loading... {int(time.monotonic() - started)}s elapsed'
+            print(('\r' if interactive else '') + message, end='' if interactive else '\n', file=stream, flush=True)
+            displayed = True
+    thread = threading.Thread(target=report, daemon=True)
+    thread.start()
+    try:
+        return callback()
+    finally:
+        stopped.set()
+        thread.join()
+        if interactive and displayed:
+            print(file=stream, flush=True)
+
+
+def _main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog='fxbx', description='Build, inspect and run compiled FXB_EX model packages.',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""Examples:
+  fxbx build ./compiled_model -o model.fxbex
+  fxbx inspect model.fxbex
+  fxbx validate model.fxbex --integrity-only
+  fxbx validate model.fxbex --weights-dir ./weights
+  fxbx run model.fxbex --input inputs.json -o result.json
+  fxbx chat model.fxbex
+  fxbx serve model.fxbex --port 8000
+  fxbx doctor
+
+Validation checks static readiness; it does not run inference or prove NPU execution.
+Model-specific exporters and capture commands belong to their adapter plugins.""")
+    sub = parser.add_subparsers(dest='action', required=True)
+    from . import __version__
+    parser.add_argument('--version',action='version',version='%(prog)s '+__version__)
+    p = sub.add_parser('build', help='Pack a compiled directory with checksums (no compilation)')
+    p.add_argument('source', help='Compiled directory containing manifest and required JSON configurations')
+    p.add_argument('-o', '--output', required=True, help='New .fxbex file; existing files are never overwritten')
+    p.add_argument('--source-model',help='Original HF model ID or HTTPS model URL')
+    p.add_argument('--source-revision',help='Original checkpoint revision (prefer immutable commit)')
+    p.add_argument('--standalone', action='store_true', help='Copy referenced external weights into the archive')
+    p = sub.add_parser('inspect', help='Verify integrity and display the manifest; no SDK needed')
+    p.add_argument('package', help='Path to a .fxbex archive')
+    p.add_argument('--memory', action='store_true', help='Show logical memory/lifetime plan without loading the NPU')
+    p = sub.add_parser('validate', help='Check integrity, SDK, adapter, weights and device availability without inference')
+    p.add_argument('package', help='Path to a .fxbex archive')
+    p.add_argument('--integrity-only', action='store_true', help='Verify archive only; skip SDK, weights and device checks')
+    p.add_argument('--weights-dir', help='Override the external checkpoint/weights directory')
+    for name in ('describe','sample'):
+        p=sub.add_parser(name,help='Show I/O contract or example input without running the model')
+        p.add_argument('package')
+    sub.add_parser('doctor', help='Report installed SDK versions and RNGD device status')
+    p = sub.add_parser('ui', help='Launch the local package interface')
+    p.add_argument('--port', type=int, default=7861, help='HTTP port (default: 7861)')
+    for name, help_text in (
+        ('run', 'Run JSON inputs or start interactive chat for a chat adapter'),
+        ('chat', 'Chat interactively, or process a messages JSON file'),
+        ('predict', 'Run a tensor DAG with named JSON inputs'),
+        ('serve', 'Serve the loaded package over local HTTP'),
+    ):
+        p = sub.add_parser(name, help=help_text, description=help_text)
+        p.add_argument('package', help='Path to a .fxbex archive')
+        p.add_argument('--verbose',action='store_true',help='Show internal SDK/compiler diagnostics on the terminal')
+        p.add_argument('--report-dir', help='Directory for runtime logs and evidence')
+        p.add_argument('--weights-dir', help='Override external checkpoint/weights directory')
+        if name != 'serve':
+            p.add_argument('--input', help='JSON file: named tensors for predict, or {"messages": [...]} for chat')
+            p.add_argument('-o', '--output', help='Write response JSON to this file')
+            p.add_argument('--max-new-tokens', type=int, default=32, help='Chat token limit (default: 32)')
+            if name == 'run':
+                p.add_argument('--sample', action='store_true', help='Run the packaged example once, including for chat models')
+                p.add_argument('--image', help='Use an image file instead of the packaged image sample')
+        else:
+            p.add_argument('--port', type=int, default=8000, help='HTTP port (default: 8000)')
+    p=sub.add_parser('fetch', help='Download a catalog release into the shared FXBEX cache')
+    p.add_argument('package')
+    p.add_argument('--refresh', action='store_true', help='Recheck catalog and force a fresh HF download')
+    p=sub.add_parser('cache', help='List or clear FXBEX-managed model downloads only')
+    p.add_argument('operation', choices=['list','clear'])
+    p.add_argument('--yes', action='store_true', help='Confirm deletion of managed model downloads')
+    args=parser.parse_args(argv)
+    if args.action=='cache':
+        from .settings import cache_root
+        root=cache_root()/'models'
+        files=sorted(root.rglob('*.fxbex')) if root.exists() else []
+        if args.operation=='clear':
+            if not args.yes:raise ValueError('Use cache clear --yes to delete FXBEX-managed downloads')
+            import shutil
+            if root.is_symlink():raise ValueError('Refusing to clear a symlinked cache root')
+            if root.exists():shutil.rmtree(root)
+        print(json.dumps({'cache':str(root),'files':[str(p) for p in files],'cleared':args.operation=='clear'}))
+        return 0
+    if args.action=='fetch':
+        from .hub import resolve_package
+        print(json.dumps({'package':str(resolve_package(args.package,refresh=args.refresh))}))
+        return 0
+    if args.action in ('run','chat','predict','serve','doctor') or (args.action=='validate' and not args.integrity_only):
+        from .settings import runtime_python
+        interpreter=runtime_python()
+        if Path(interpreter)!=Path(sys.executable):
+            import subprocess
+            print('Using SDK Python: '+interpreter,file=sys.stderr,flush=True)
+            code=subprocess.call([interpreter,'-m','fxbx',*(sys.argv[1:] if argv is None else map(str,argv))])
+            return code if code>=0 else 128-code
+    if args.action=='chat' and not args.input:
+        print('Welcome to FXBEX Chat!\nModel: '+args.package+
+              '\n모델을 준비하고 있습니다. 적재가 완료되면 >>> 뒤에 질문을 입력하세요.'+
+              '\n/reset: 대화 초기화 · /quit: 종료 및 모델 해제\n',file=sys.stderr,flush=True)
+    if args.action in ('run','chat','predict','serve','describe','sample','inspect','validate'):
+        from .hub import resolve_package
+        args.package=str(resolve_package(args.package))
+    sample_contract=None
+    if args.action=='run' and args.image and args.input:
+        raise ValueError('Use --image or --input, not both')
+    if args.action=='run' and not args.input:
+        from .schema import describe
+        sample_contract=describe(args.package)
+        if args.image and (sample_contract['method']!='predict' or 'image' not in sample_contract['inputs']):
+            raise ValueError('This package does not declare an image input; inspect its input contract')
+        if args.image and not Path(args.image).is_file():
+            raise ValueError('Image file does not exist')
+        if sample_contract['method']=='chat' and not args.sample:
+            sample_contract=None
+    if args.action=='build':result={'package':str(build(args.source,args.output,standalone=args.standalone,source_url=args.source_model,source_revision=args.source_revision))}
+    elif args.action == 'inspect':
+        m=inspect(args.package)
+        result={'model':m['model'],'runtime':m['runtime'],'compatibility':m['compatibility'],
+                'standalone':m['standalone'],'bundled_python':bool(m['runtime'].get('bundled_python')),
+                'delivery':m.get('delivery'), 'provenance':m.get('provenance',{'status':'unknown'}), 'files':len(m['files']),
+                'artifact_bytes':sum(x['size'] for x in m['files'].values()),'integrity_verified':True}
+        if args.memory:
+            from .memory import inspect_archive, summarize
+            result['memory_plan'] = summarize(inspect_archive(args.package))
+    elif args.action == 'validate':
+        result = validate(args.package, integrity_only=args.integrity_only, weights_dir=args.weights_dir)
+    elif args.action in ('describe','sample'):
+        from .schema import describe,example_inputs
+        result=describe(args.package) if args.action=='describe' else example_inputs(args.package)
+    elif args.action=='doctor':
+        from .runtime import doctor
+        result=doctor()
+    elif args.action=='ui':
+        from .ui import launch
+        launch(args.port);return
+    else:
+        from .runtime import Session
+        # SDK/compiler diagnostics may print; keep JSON results on stdout.
+        import contextlib
+        if args.action == 'predict' and not args.input:
+            raise ValueError('--input JSON file is required for tensor prediction')
+        from .runtime import package_compatibility
+        session=Session(args.package,report_dir=args.report_dir,weights_dir=args.weights_dir)
+        log_path=session.report_dir/'runtime.log'
+        print(f'Loading package; diagnostics: {log_path}',file=sys.stderr,flush=True)
+        def invoke(callback):return _runtime_call(callback,log_path,args.verbose)
+        progress_stream = sys.stderr
+        _load_with_progress(lambda: invoke(session.__enter__), progress_stream)
+        try:
+            for message in package_compatibility(session.manifest):
+                print('Warning: '+message,file=sys.stderr,flush=True)
+            print(f'NPU package ready; reports: {session.report_dir}',file=sys.stderr,flush=True)
+            from .execution import memory_text
+            print('Memory: '+memory_text(getattr(session,'memory',None)),file=sys.stderr,flush=True)
+            if args.action=='serve':
+                from .server import serve
+                serve(session,args.port,invoke=invoke);return
+            if sample_contract is not None:
+                from .schema import resolve_sample
+                data=resolve_sample(sample_contract,session.root,session.manifest)
+                if args.image:
+                    data['image']=str(Path(args.image).resolve())
+                if sample_contract['method']=='chat':
+                    result=invoke(lambda: session.chat(data['messages'],data.get('max_new_tokens',args.max_new_tokens)))
+                else:result=invoke(lambda: session.predict(data))
+            elif args.action=='predict' or (args.action=='run' and session.manifest['runtime']['adapter']=='runnable_dag'):
+                if not args.input:raise ValueError('--input JSON file is required for tensor prediction')
+                result=invoke(lambda: session.predict(json.loads(Path(args.input).read_text())))
+            elif args.input:
+                data=json.loads(Path(args.input).read_text())
+                result=invoke(lambda: session.chat(data['messages'],data.get('max_new_tokens',args.max_new_tokens)))
+            else:
+                messages=[]
+                print('모델 적재 완료. 대화를 시작하세요. (/reset: 초기화 · /quit: 종료)',flush=True)
+                while True:
+                    try:prompt=input('>>> ')
+                    except EOFError:break
+                    if prompt.strip()=='/quit':break
+                    if prompt.strip()=='/reset':messages=[];continue
+                    if not prompt.strip():continue
+                    candidate=messages+[{'role':'user','content':prompt}]
+                    result=invoke(lambda: session.chat(candidate,args.max_new_tokens))
+                    messages=candidate+[{'role':'assistant','content':result['text']}]
+                    print(result['text'],flush=True)
+                return
+            if isinstance(result,dict):result.setdefault('memory',getattr(session,'memory',None))
+        finally:invoke(lambda: session.__exit__(None,None,None))
+        result['report_dir']=str(session.report_dir)
+        result_path=Path(args.output).resolve() if args.output else session.report_dir/'result.json'
+        result['result_file']=str(result_path)
+        result_path.write_text(json.dumps(result,ensure_ascii=False,indent=2))
+        if not args.verbose:
+            # Full raw diagnostics remain in result.json and runtime.log.
+            result={key:value for key,value in result.items() if key not in
+                    ('memory','compiler_calls','replay_hits','npu_tasks','validated_audit','current_request_traced')}
+    print(json.dumps(result,ensure_ascii=False,indent=2))
+    return 0 if result.get('valid', True) else 1
+
+def main(argv=None):
+    try:
+        return _main(argv) or 0
+    except Exception as exc:
+        print(f'fxbx: {exc}', file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == '__main__':
+    sys.exit(main())

fxbex/execution.py

@@ -0,0 +1,113 @@
+"""Small execution receipts, not a replacement for official NPU trace verification."""
+import hashlib
+import json
+import time
+from pathlib import Path
+import subprocess
+
+def memory_text(snapshot):
+    snapshot=snapshot or {}
+    logical=snapshot.get('model_logical_memory',{})
+    values=[]
+    for key,label in [('weight_logical_bytes','weights'),('kv_logical_bytes','KV'),('recurrent_logical_bytes','recurrent')]:
+        if key in logical:values.append(f"{label}={logical[key]/1024**3:.3f} GiB")
+    execution=logical.get('execution') or {}
+    if 'peak_live_tensor_logical_bytes' in execution:
+        values.append(f"live tensor peak={execution['peak_live_tensor_logical_bytes']/1024**2:.2f} MiB")
+        values.append(f"released bindings={execution.get('released_tensor_bindings',0)}")
+    return 'physical HBM unmeasured; SMI zero is inconclusive. Logical NPU tensors: '+(', '.join(values) or 'not reported')
+
+
+
+class MemoryTelemetry:
+    """Best-effort SMI memory snapshots; never an allocator substitute."""
+    def __init__(self, report_dir, interval_s=5):
+        self.path = Path(report_dir) / 'memory.jsonl'
+        self.last = None
+        self.interval_s = interval_s
+        self.last_sample_monotonic = None
+
+    def sample(self, phase, *, force=False):
+        now = time.monotonic()
+        boundary = phase in ('before_load', 'after_load', 'after_unload')
+        if (self.last is not None and not boundary and not force
+                and now-self.last_sample_monotonic < self.interval_s):
+            return dict(self.last, requested_phase=phase, cached_snapshot=True,
+                        sample_age_s=now-self.last_sample_monotonic)
+        row = {'schema': 1, 'phase': phase, 'time_unix': time.time(),
+               'source': 'furiosa-smi status --format json',
+               'physical_allocated_bytes':None,
+               'note':'SMI-reported counters are not allocator proof; zero does not establish zero HBM use.'}
+        try:
+            result = subprocess.run(['furiosa-smi', 'status', '--format', 'json'],
+                                    capture_output=True, text=True, timeout=5, check=True)
+            row['devices'] = json.loads(result.stdout)
+        except (OSError, subprocess.SubprocessError, json.JSONDecodeError) as exc:
+            row['error_type'] = type(exc).__name__
+        self.last = row
+        self.last_sample_monotonic = now
+        try:
+            with self.path.open('a') as stream:
+                stream.write(json.dumps(row, allow_nan=False) + '\n')
+        except (OSError,ValueError,TypeError):
+            # A diagnostic must never hide model execution or cleanup failures.
+            pass
+        return row
+
+
+def manifest_identity(manifest):
+    # The validated manifest already contains hashes of packaged artifacts.
+    # Hashing it avoids rereading multi-GB weights for every inference.
+    data = json.dumps(manifest, sort_keys=True, separators=(',', ':'), allow_nan=False)
+    return hashlib.sha256(data.encode()).hexdigest()
+
+
+class ExecutionRecorder:
+    def __init__(self, report_dir, manifest):
+        self.path = Path(report_dir) / 'executions.jsonl'
+        self.identity = manifest_identity(manifest)
+        self.sequence = 0
+        self.last = None
+        self.backend=manifest.get('optimization',{}).get('backend',
+            'torch_runnable' if manifest.get('runtime',{}).get('adapter') in ('qwen35_replay','runnable_dag') else 'unknown')
+
+    def call(self, operation, callback):
+        self.sequence += 1
+        started = time.perf_counter()
+        row = {'schema': 1, 'sequence': self.sequence, 'operation': operation,
+               'manifest_sha256': self.identity, 'status': 'failed',
+               'timing_scope': 'host call including dispatch/transfers/waits; completion is adapter-defined',
+               'npu_verdict': 'unknown', 'support_status': 'not_established',
+               'optimization_status': 'not_measured', 'adapter_reported': {}}
+        row.update(backend=self.backend,measurement_scope='adapter_defined_return',
+                   unit='seconds',clock_domain='host_monotonic',completion_confirmed=None,
+                   profiling_enabled=None)
+        try:
+            result = callback()
+            row['status'] = 'succeeded'
+            if isinstance(result, dict):
+                # Never save prompts, messages, tensor outputs or arbitrary adapter data.
+                for key in ('compiler_calls', 'npu_tasks', 'current_request_traced'):
+                    value = result.get(key)
+                    if type(value) in (int, bool) or value is None:
+                        row['adapter_reported'][key] = value
+                for key in ('validated_audit',):
+                    value = result.get(key)
+                    if isinstance(value, str) and len(value) <= 4096:
+                        row['adapter_reported'][key] = value
+            return result
+        except BaseException as exc:
+            row['error_type'] = type(exc).__name__
+            raise
+        finally:
+            row['wall_seconds'] = time.perf_counter() - started
+            row['report_path'] = str(self.path)
+            self.last = row
+            row['persisted'] = True
+            try:
+                with self.path.open('a') as stream:
+                    stream.write(json.dumps(row, allow_nan=False) + '\n')
+            except OSError as exc:
+                # Telemetry failure must not hide the original model exception.
+                row['persisted'] = False
+                row['recording_error_type'] = type(exc).__name__