superii-sdk 0.1.0__tar.gz

superii_sdk-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# local Cloudflare deployment state
+.wrangler/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Python bytecode
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+
+# Super ii Runtime local state (uploads and generated artifacts never enter Git)
+runtime/data/
+runtime/workspaces/
+rust/target/
+
+
+# environment variables
+.env
+.env.*
+.dev.vars
+!.env.example
+
+# local visual QA captures (the written QA record remains tracked)
+qa/evidence/
+
+# macOS-specific files
+.DS_Store
+
+# jetbrains setting folder
+.idea/

superii_sdk-0.1.0/LICENSE

@@ -0,0 +1,13 @@
+Modified MIT License
+
+Copyright (c) 2026 Super ii 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Our only modification part is that, if the Software (or any derivative works thereof) is used for any of your commercial products or services that have more than 1000 monthly active users, or more than 10000 US dollars (or equivalent in other currencies) in monthly revenue, you shall at all times prominently display "www.superii.site" on the user interface of such product or service.

superii_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: superii-sdk
+Version: 0.1.0
+Summary: Verified Super ii model acquisition, hardware planning and local inference
+Project-URL: Homepage, https://superii.site
+Project-URL: Source, https://github.com/smavgs/super-ii/tree/main/sdk/python
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cryptography<51,>=46
+Requires-Dist: filelock<4,>=3.19
+Requires-Dist: httpx<0.29,>=0.28
+Requires-Dist: psutil<8,>=7
+Provides-Extra: mlx
+Requires-Dist: mlx-lm<1,>=0.30; (sys_platform == 'darwin') and extra == 'mlx'
+Provides-Extra: serve
+Requires-Dist: fastapi<1,>=0.115; extra == 'serve'
+Requires-Dist: mcp<2,>=1.20; extra == 'serve'
+Requires-Dist: uvicorn<1,>=0.35; extra == 'serve'
+Provides-Extra: test
+Requires-Dist: fastapi<1,>=0.115; extra == 'test'
+Requires-Dist: mcp<2,>=1.20; extra == 'test'
+Requires-Dist: pytest<10,>=9; extra == 'test'
+Requires-Dist: ruff<1,>=0.16; extra == 'test'
+Provides-Extra: transformers
+Requires-Dist: accelerate<2,>=1.10; extra == 'transformers'
+Requires-Dist: safetensors<1,>=0.6; extra == 'transformers'
+Requires-Dist: torch<3,>=2.8; extra == 'transformers'
+Requires-Dist: transformers<6,>=5; extra == 'transformers'
+Description-Content-Type: text/markdown
+
+# Super ii Python SDK
+
+Install the package (Python 3.11 or newer):
+
+```sh
+python -m pip install superii-sdk
+```
+
+The distribution is named `superii-sdk`; the import and CLI are named `superii`.
+For a source checkout, use `python -m pip install ./sdk/python` instead.
+
+```python
+import superii
+
+print(superii.hardware())  # stays on this machine
+print(superii.inspect("owner/model"))  # metadata, immutable files and evidence
+print(superii.plan("owner/model"))  # estimates and explains before loading
+with superii.load("owner/model") as model:
+    print(model.generate("Hello", max_tokens=128))
+```
+
+The catalogue remains intentionally empty before creator submissions. The
+example repository is a placeholder, not a seeded or downloadable model.
+
+`load` resolves one published commit, plans against available memory, downloads
+only its selected files, verifies every SHA-256, checks memory again and invokes
+an installed runtime. Pass `revision="<full 64-character commit>"` for reproducible
+notebooks, applications, training inputs and CI. `pull` returns a `Snapshot` with
+its path and manifest; `verify(snapshot)` rechecks bytes. `await superii.apull(...)`
+and `Client.prefetch(...)` support asynchronous/background acquisition.
+
+Install llama.cpp's `llama-server` from its official distribution for GGUF.
+Optional extras `superii-sdk[mlx]`, `superii-sdk[transformers]` and
+`superii-sdk[serve]` add those integrations;
+install vLLM using its hardware-specific official instructions. Nothing installs
+or recompiles a backend behind the user's back. The initial planner supports
+single-file GGUF and known text architectures with safetensors. Unsupported
+architectures, custom Python, split GGUF and ambiguous conversions fail with a
+reason. The vLLM and Transformers offline adapters currently return a complete
+response rather than token streaming.
+
+Memory estimates include OS headroom and context overhead, but are not a zero-OOM
+guarantee. Existing smaller or quantized artifacts are preferred to inventing a
+conversion. GPU support must be present in the installed runtime; compatibility
+metadata is not a benchmark. `lazy_weights=True` enables the installed MLX
+loader's lazy evaluation of already-verified local weights; it does not execute
+partially downloaded weights.
+
+Downloads use strict ranges, resume partial chunks, verify the final file and
+deduplicate content within each authenticated cache. Redirects cannot forward
+credentials; private content uses a separate credential-scoped cache. Set
+`SUPERII_TOKEN` to an existing scoped token with `repository:read` to access an
+authorized private published release. Every new pull rechecks canonical access,
+even when bytes are cached. Files already intentionally downloaded by their
+authorized owner remain local; revocation cannot erase an owner's copies.
+
+```python
+with superii.load("owner/model") as model:
+    model.serve(port=8765, token=your_random_local_token)  # loopback OpenAI text API
+    # Or model.serve_mcp() for a stdio MCP inference tool.
+```
+
+The OpenAI endpoint requires a token and rejects browser origins. It implements
+non-streaming text completions and chat completions; it does not claim full
+OpenAI API parity. MCP exposes one inference tool and does not itself configure
+an agent's model provider. Repository content and model output remain untrusted.
+
+An optional explicit `Client(peers=(Peer("https://cache.example", peer_token),))`
+can use a peer cache. No discovery or LAN broadcasts occur. Private artifacts
+always bypass peers. `superii.serving.create_cache_app` serves already-cached
+public hashes only, after fresh canonical visibility checks. Deploy that optional
+service with TLS and a separate strong peer credential; otherwise leave peers
+unset. Outages, missing data and corrupted peer bytes fall back to the origin.
+
+Canonical manifests are hashes, not publisher identity proofs. New automatic
+publication also returns an Ed25519 policy attestation; verification and key
+pinning are documented with the publication service. Historical releases retain
+their historical evidence and are not silently relabeled.
+
+## Measurements and acquisition research
+
+`superii benchmark owner/model "Hello" --max-tokens 128` records first output,
+generation time, approximate tokens per second, sampled process-tree peak RSS
+and bytes acquired before inference. Batch adapters label first-output time
+separately from token-streaming TTFT. RSS does not measure all GPU allocations.
+Run cold and warm cache trials separately; the tool does not clear the OS cache.
+
+`superii.experiments.tensor_ranges(snapshot)` indexes verified safetensors, and
+`iter_tensor_bytes(snapshot, prefix="model.layers.0.")` performs bounded mmap
+reads for layer or expert experiments. These are tested access primitives;
+arbitrary models do not yet execute with partial weights. All files must pass
+full verification first. Quantization/conversion, layer scheduling and MoE
+expert selection require an architecture-specific implementation and benchmark.
+
+Optional remote warm-start is explicit at each remote request:
+
+```python
+from superii.remote import RemoteModel
+
+# This call sends the prompt to your chosen provider. Use its separate token.
+# Local pull/load may run concurrently in your application's executor.
+with RemoteModel("https://your-provider.example", "model-id", token=provider_token) as remote:
+    answer = remote.generate("Hello")
+# Switch to your completed local Model for later requests when you choose.
+```
+
+This adapter implements the provider's non-streaming `/v1/completions` contract.
+It never reuses Super ii credentials, follows redirects, silently falls back to
+remote execution, or asserts that remote and local model outputs are identical.
+
+Sources: [llama.cpp server](https://github.com/ggml-org/llama.cpp/tree/master/tools/server),
+[MLX LM](https://github.com/ml-explore/mlx-lm),
+[vLLM](https://docs.vllm.ai/en/latest/),
+[safetensors](https://huggingface.co/docs/safetensors/),
+[MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk).

superii_sdk-0.1.0/README.md

@@ -0,0 +1,115 @@
+# Super ii Python SDK
+
+Install the package (Python 3.11 or newer):
+
+```sh
+python -m pip install superii-sdk
+```
+
+The distribution is named `superii-sdk`; the import and CLI are named `superii`.
+For a source checkout, use `python -m pip install ./sdk/python` instead.
+
+```python
+import superii
+
+print(superii.hardware())  # stays on this machine
+print(superii.inspect("owner/model"))  # metadata, immutable files and evidence
+print(superii.plan("owner/model"))  # estimates and explains before loading
+with superii.load("owner/model") as model:
+    print(model.generate("Hello", max_tokens=128))
+```
+
+The catalogue remains intentionally empty before creator submissions. The
+example repository is a placeholder, not a seeded or downloadable model.
+
+`load` resolves one published commit, plans against available memory, downloads
+only its selected files, verifies every SHA-256, checks memory again and invokes
+an installed runtime. Pass `revision="<full 64-character commit>"` for reproducible
+notebooks, applications, training inputs and CI. `pull` returns a `Snapshot` with
+its path and manifest; `verify(snapshot)` rechecks bytes. `await superii.apull(...)`
+and `Client.prefetch(...)` support asynchronous/background acquisition.
+
+Install llama.cpp's `llama-server` from its official distribution for GGUF.
+Optional extras `superii-sdk[mlx]`, `superii-sdk[transformers]` and
+`superii-sdk[serve]` add those integrations;
+install vLLM using its hardware-specific official instructions. Nothing installs
+or recompiles a backend behind the user's back. The initial planner supports
+single-file GGUF and known text architectures with safetensors. Unsupported
+architectures, custom Python, split GGUF and ambiguous conversions fail with a
+reason. The vLLM and Transformers offline adapters currently return a complete
+response rather than token streaming.
+
+Memory estimates include OS headroom and context overhead, but are not a zero-OOM
+guarantee. Existing smaller or quantized artifacts are preferred to inventing a
+conversion. GPU support must be present in the installed runtime; compatibility
+metadata is not a benchmark. `lazy_weights=True` enables the installed MLX
+loader's lazy evaluation of already-verified local weights; it does not execute
+partially downloaded weights.
+
+Downloads use strict ranges, resume partial chunks, verify the final file and
+deduplicate content within each authenticated cache. Redirects cannot forward
+credentials; private content uses a separate credential-scoped cache. Set
+`SUPERII_TOKEN` to an existing scoped token with `repository:read` to access an
+authorized private published release. Every new pull rechecks canonical access,
+even when bytes are cached. Files already intentionally downloaded by their
+authorized owner remain local; revocation cannot erase an owner's copies.
+
+```python
+with superii.load("owner/model") as model:
+    model.serve(port=8765, token=your_random_local_token)  # loopback OpenAI text API
+    # Or model.serve_mcp() for a stdio MCP inference tool.
+```
+
+The OpenAI endpoint requires a token and rejects browser origins. It implements
+non-streaming text completions and chat completions; it does not claim full
+OpenAI API parity. MCP exposes one inference tool and does not itself configure
+an agent's model provider. Repository content and model output remain untrusted.
+
+An optional explicit `Client(peers=(Peer("https://cache.example", peer_token),))`
+can use a peer cache. No discovery or LAN broadcasts occur. Private artifacts
+always bypass peers. `superii.serving.create_cache_app` serves already-cached
+public hashes only, after fresh canonical visibility checks. Deploy that optional
+service with TLS and a separate strong peer credential; otherwise leave peers
+unset. Outages, missing data and corrupted peer bytes fall back to the origin.
+
+Canonical manifests are hashes, not publisher identity proofs. New automatic
+publication also returns an Ed25519 policy attestation; verification and key
+pinning are documented with the publication service. Historical releases retain
+their historical evidence and are not silently relabeled.
+
+## Measurements and acquisition research
+
+`superii benchmark owner/model "Hello" --max-tokens 128` records first output,
+generation time, approximate tokens per second, sampled process-tree peak RSS
+and bytes acquired before inference. Batch adapters label first-output time
+separately from token-streaming TTFT. RSS does not measure all GPU allocations.
+Run cold and warm cache trials separately; the tool does not clear the OS cache.
+
+`superii.experiments.tensor_ranges(snapshot)` indexes verified safetensors, and
+`iter_tensor_bytes(snapshot, prefix="model.layers.0.")` performs bounded mmap
+reads for layer or expert experiments. These are tested access primitives;
+arbitrary models do not yet execute with partial weights. All files must pass
+full verification first. Quantization/conversion, layer scheduling and MoE
+expert selection require an architecture-specific implementation and benchmark.
+
+Optional remote warm-start is explicit at each remote request:
+
+```python
+from superii.remote import RemoteModel
+
+# This call sends the prompt to your chosen provider. Use its separate token.
+# Local pull/load may run concurrently in your application's executor.
+with RemoteModel("https://your-provider.example", "model-id", token=provider_token) as remote:
+    answer = remote.generate("Hello")
+# Switch to your completed local Model for later requests when you choose.
+```
+
+This adapter implements the provider's non-streaming `/v1/completions` contract.
+It never reuses Super ii credentials, follows redirects, silently falls back to
+remote execution, or asserts that remote and local model outputs are identical.
+
+Sources: [llama.cpp server](https://github.com/ggml-org/llama.cpp/tree/master/tools/server),
+[MLX LM](https://github.com/ml-explore/mlx-lm),
+[vLLM](https://docs.vllm.ai/en/latest/),
+[safetensors](https://huggingface.co/docs/safetensors/),
+[MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk).

superii_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "superii-sdk"
+version = "0.1.0"
+description = "Verified Super ii model acquisition, hardware planning and local inference"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["httpx>=0.28,<0.29", "filelock>=3.19,<4", "psutil>=7,<8", "cryptography>=46,<51"]
+
+[project.optional-dependencies]
+mlx = ["mlx-lm>=0.30,<1; sys_platform == 'darwin'"]
+transformers = ["transformers>=5,<6", "torch>=2.8,<3", "safetensors>=0.6,<1", "accelerate>=1.10,<2"]
+serve = ["fastapi>=0.115,<1", "uvicorn>=0.35,<1", "mcp>=1.20,<2"]
+test = ["pytest>=9,<10", "ruff>=0.16,<1", "fastapi>=0.115,<1", "mcp>=1.20,<2"]
+
+[project.scripts]
+superii = "superii.cli:main"
+
+[project.urls]
+Homepage = "https://superii.site"
+Source = "https://github.com/smavgs/super-ii/tree/main/sdk/python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/superii"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

superii_sdk-0.1.0/src/superii/__init__.py

@@ -0,0 +1,84 @@
+"""Super ii: inspect, plan, verify and run immutable local models."""
+
+from __future__ import annotations
+
+from .client import Client, Peer, Snapshot
+from .errors import IntegrityError, PlanError, SuperiiError
+from .hardware import Hardware, hardware
+from .manifest import Manifest
+from .model import Model
+from .planner import Plan
+from .planner import plan as _plan
+
+__version__ = "0.1.0"
+__all__ = [
+    "Client",
+    "Peer",
+    "Snapshot",
+    "IntegrityError",
+    "PlanError",
+    "SuperiiError",
+    "Hardware",
+    "hardware",
+    "Manifest",
+    "Model",
+    "Plan",
+    "inspect",
+    "plan",
+    "pull",
+    "apull",
+    "verify",
+    "load",
+]
+
+
+def inspect(repository: str, *, revision: str | None = None, **client_options) -> Manifest:
+    with Client(**client_options) as client:
+        return client.inspect(repository, revision=revision)
+
+
+def plan(
+    repository: str | Manifest,
+    *,
+    machine: Hardware | None = None,
+    runtime: str | None = None,
+    context_size: int = 4096,
+    revision: str | None = None,
+    **client_options,
+) -> Plan:
+    manifest = (
+        repository
+        if isinstance(repository, Manifest)
+        else inspect(repository, revision=revision, **client_options)
+    )
+    return _plan(manifest, machine or hardware(), runtime=runtime, context_size=context_size)
+
+
+def pull(repository: str, *, revision: str | None = None, **client_options) -> Snapshot:
+    with Client(**client_options) as client:
+        return client.pull(repository, revision=revision)
+
+
+async def apull(repository: str, *, revision: str | None = None, **client_options) -> Snapshot:
+    with Client(**client_options) as client:
+        return await client.apull(repository, revision=revision)
+
+
+def verify(snapshot: Snapshot) -> bool:
+    return snapshot.verify()
+
+
+def load(
+    repository: str,
+    *,
+    revision: str | None = None,
+    runtime: str | None = None,
+    context_size: int = 4096,
+    lazy_weights: bool = False,
+    **client_options,
+) -> Model:
+    with Client(**client_options) as client:
+        manifest = client.inspect(repository, revision=revision)
+        selected = _plan(manifest, hardware(), runtime=runtime, context_size=context_size)
+        snapshot = client.pull(repository, revision=selected.revision, files=selected.files)
+    return Model(snapshot, selected, lazy_weights=lazy_weights)

superii_sdk-0.1.0/src/superii/attestation.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import base64
+import json
+from collections.abc import Mapping
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from .errors import IntegrityError
+from .manifest import Manifest
+
+
+def verify_attestation(manifest: Manifest, trusted_keys: Mapping[str, str]) -> bool:
+    proof = manifest.publication
+    if not proof:
+        raise IntegrityError("This release has no automatic publication attestation")
+    try:
+        key = trusted_keys[proof["key_id"]]
+        payload = proof["payload"]
+        Ed25519PublicKey.from_public_bytes(base64.b64decode(key, validate=True)).verify(
+            base64.b64decode(proof["signature"], validate=True),
+            payload.encode(),
+        )
+        data = json.loads(payload)
+        if (
+            data["manifest_sha256"] != manifest.manifest_sha256
+            or data["repository_id"] != manifest.repository_id
+            or data["revision_id"] != manifest.revision_id
+            or data["commit_sha"] != manifest.revision
+            or data["outcome"] != "passed"
+            or data["policy_version"] != "superii-auto-publish-v1"
+        ):
+            raise IntegrityError("Publication attestation does not approve this manifest")
+    except (KeyError, TypeError, ValueError, InvalidSignature) as error:
+        raise IntegrityError(
+            "Publication signature is missing, invalid or signed by an untrusted key"
+        ) from error
+    return True

superii_sdk-0.1.0/src/superii/cli.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import asdict
+
+
+def main() -> None:
+    from . import Client, hardware, load, plan
+    from .experiments import benchmark
+
+    parser = argparse.ArgumentParser(prog="superii")
+    parser.add_argument("--base-url", default="https://superii.site")
+    parser.add_argument("--cache-dir")
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("hardware")
+    for name in ("inspect", "plan", "pull", "generate", "benchmark", "mcp", "serve"):
+        sub = commands.add_parser(name)
+        sub.add_argument("repository")
+        sub.add_argument("--revision")
+        if name in {"plan", "generate", "benchmark", "mcp", "serve"}:
+            sub.add_argument("--runtime", choices=["llama.cpp", "mlx", "transformers", "vllm"])
+            sub.add_argument("--context-size", type=int, default=4096)
+        if name in {"generate", "benchmark"}:
+            sub.add_argument("prompt")
+            sub.add_argument("--max-tokens", type=int, default=128)
+        if name == "serve":
+            sub.add_argument("--port", type=int, default=8765)
+    args = parser.parse_args()
+    if args.command == "hardware":
+        print(json.dumps(asdict(hardware()), indent=2))
+        return
+    options = {"base_url": args.base_url, "cache_dir": args.cache_dir}
+    if args.command in {"inspect", "pull"}:
+        with Client(**options) as client:
+            result = getattr(client, args.command)(args.repository, revision=args.revision)
+        print(json.dumps(asdict(result), indent=2, default=str))
+    elif args.command == "plan":
+        print(
+            json.dumps(
+                asdict(
+                    plan(
+                        args.repository,
+                        revision=args.revision,
+                        runtime=args.runtime,
+                        context_size=args.context_size,
+                        **options,
+                    )
+                ),
+                indent=2,
+            )
+        )
+    else:
+        with load(
+            args.repository,
+            revision=args.revision,
+            runtime=args.runtime,
+            context_size=args.context_size,
+            **options,
+        ) as model:
+            if args.command == "mcp":
+                model.serve_mcp()
+            elif args.command == "serve":
+                import os
+
+                token = os.environ.get("SUPERII_SERVING_TOKEN", "")
+                if len(token) < 32:
+                    parser.error(
+                        "Set SUPERII_SERVING_TOKEN to a random local token (32+ characters)"
+                    )
+                model.serve(port=args.port, token=token)
+            elif args.command == "benchmark":
+                print(
+                    json.dumps(benchmark(model, args.prompt, max_tokens=args.max_tokens), indent=2)
+                )
+            else:
+                print(model.generate(args.prompt, max_tokens=args.max_tokens))