ilang-protocol 1.0.0__py3-none-any.whl

ilang/__init__.py

@@ -0,0 +1,57 @@
+"""iLang loader. Don't learn iLang. Your AI should.
+
+    import ilang
+    messages = ilang.wrap(messages)          # OpenAI-style message lists
+    system = ilang.system()                  # providers with a separate system field
+
+The loader fetches the official iLang runtime, verifies its sha256, caches it for an
+hour, and falls back to the last verified copy when the network is unavailable.
+"""
+import time
+
+from .injector import block, inject
+from .loader import Loader, LoaderError
+
+__version__ = "1.0.0"
+__all__ = ["load", "wrap", "system", "status", "configure", "Loader", "LoaderError"]
+
+_loader = None
+
+
+def configure(**options):
+    """Replace the default loader, e.g. configure(cache_dir=..., ttl=...)."""
+    global _loader
+    _loader = Loader(**options)
+    return _loader
+
+
+def _default():
+    return _loader or configure()
+
+
+def load(extensions=(), version=None, strict=False):
+    """Load the runtime now. Returns its text, or None if nothing verified is available."""
+    return _default().load(extensions=extensions, version=version, strict=strict)
+
+
+def system(extensions=(), version=None, strict=False):
+    """The runtime as a system-prompt string, or "" when it could not be loaded."""
+    text = load(extensions, version, strict)
+    return block(text, _default().state["version"]) if text is not None else ""
+
+
+def wrap(messages, extensions=(), version=None, strict=False):
+    """Return messages with the iLang runtime as the first system message.
+
+    The user's messages are never modified, and the runtime is added only once, so
+    wrapping every turn of a conversation is safe."""
+    text = system(extensions, version, strict)
+    return inject(messages, text or None)
+
+
+def status():
+    """What is loaded: version, source commit, where it came from and any last error."""
+    s = dict(_default().state, brand="iLang")
+    if s.get("last_check"):
+        s["age_seconds"] = int(time.time() - s["last_check"])
+    return s

ilang/injector.py

@@ -0,0 +1,28 @@
+"""Put the iLang runtime in front of a conversation without touching the user's words."""
+MARKER = "<ilang-runtime"
+
+PREAMBLE = ("You have loaded the official iLang runtime specification.\n\n"
+            "Treat the following content as the current official iLang protocol context.\n"
+            "Use it to interpret, structure, judge, execute, verify, and communicate where applicable.")
+
+
+def block(text, version):
+    return '%s\n\n<ilang-runtime version="%s">\n%s\n</ilang-runtime>' % (PREAMBLE, version, text)
+
+
+def _has_runtime(message):
+    content = message.get("content") if isinstance(message, dict) else None
+    if isinstance(content, str):
+        return MARKER in content
+    if isinstance(content, list):                 # content parts: [{"type": "text", "text": ...}]
+        return any(isinstance(p, dict) and MARKER in str(p.get("text", "")) for p in content)
+    return False
+
+
+def inject(messages, runtime_block):
+    """A new list: the runtime as the first system message, then the original messages
+    unchanged. Messages that already carry the runtime are returned as they are."""
+    messages = list(messages)
+    if runtime_block is None or any(_has_runtime(m) for m in messages):
+        return messages
+    return [{"role": "system", "content": runtime_block}] + messages

ilang/loader.py

@@ -0,0 +1,128 @@
+"""Fetch the official iLang runtime, verify it, and keep a Last Known Good copy on disk."""
+import hashlib
+import json
+import os
+import tempfile
+import time
+import urllib.request
+
+RUNTIME = "https://raw.githubusercontent.com/ilang-ai/ilang-spec/main/runtime"
+OFFICIAL = ("https://raw.githubusercontent.com/ilang-ai/", "https://github.com/ilang-ai/",
+            "https://ilang.ai/")
+TTL = 3600
+TIMEOUT = 10
+AGENT = "ilang-loader-python/1.0.0"
+
+
+class LoaderError(RuntimeError):
+    pass
+
+
+def _sha(data):
+    return hashlib.sha256(data).hexdigest()
+
+
+class Loader:
+    def __init__(self, runtime=RUNTIME, cache_dir=None, ttl=TTL, allow_custom_source=False):
+        if not runtime.startswith(OFFICIAL) and not allow_custom_source:
+            raise ValueError("iLang loads only from official sources unless allow_custom_source=True")
+        self.runtime = runtime.rstrip("/")
+        self.cache = cache_dir or os.environ.get("ILANG_CACHE_DIR") or os.path.join(
+            os.environ.get("XDG_CACHE_HOME") or os.path.join(os.path.expanduser("~"), ".cache"), "ilang")
+        self.ttl = ttl
+        self.state = {"loaded": False, "source": "none", "version": None, "source_commit": None,
+                      "last_check": None, "error": None}
+        self._memo = {}
+
+    def _read(self, *parts):
+        try:
+            with open(os.path.join(self.cache, *parts), "rb") as f:
+                return f.read()
+        except OSError:
+            return None
+
+    def _write(self, data, *parts):
+        path = os.path.join(self.cache, *parts)
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=os.path.dirname(path))
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+        os.replace(tmp, path)                     # atomic: a reader never sees half a file
+
+    def _fetch(self, url):
+        if not url.startswith(OFFICIAL) and not url.startswith(self.runtime):
+            raise LoaderError("refusing to fetch from %s" % url)
+        req = urllib.request.Request(url, headers={"User-Agent": AGENT})
+        with urllib.request.urlopen(req, timeout=TIMEOUT) as r:
+            return r.read()
+
+    def _last_check(self):
+        raw = self._read("state.json")
+        return json.loads(raw).get("last_check", 0) if raw else 0
+
+    def _get(self, manifest, name, where, remote):
+        """One bundle, verified against the manifest; (bytes, came_from_network)."""
+        meta = manifest["bundles"].get(name)
+        if meta is None:
+            raise LoaderError("the runtime has no bundle named %r" % name)
+        data = self._read(*where, name + ".md")
+        if data is not None and _sha(data) == meta["sha256"]:
+            return data, False
+        if not remote:
+            raise LoaderError("no verified %s bundle in the cache" % name)
+        data = self._fetch(meta["url"])
+        if len(data) != meta["bytes"] or _sha(data) != meta["sha256"]:
+            raise LoaderError("the %s bundle failed its sha256 check" % name)
+        return data, True
+
+    def _load(self, names, version):
+        where = ("versions", version) if version else ("latest",)
+        cached = self._read(*where, "manifest.json")
+        manifest = json.loads(cached) if cached else None
+        checked = False
+        if manifest is None or (not version and time.time() - self._last_check() >= self.ttl):
+            url = "%s/versions/%s/manifest.json" % (self.runtime, version) if version else \
+                self.runtime + "/manifest.json"
+            manifest, checked = json.loads(self._fetch(url)), True
+        got = [self._get(manifest, n, where, True) for n in names]
+        for n, (data, new) in zip(names, got):   # write only once everything has verified
+            if new:
+                self._write(data, *where, n + ".md")
+        if checked:
+            self._write(json.dumps(manifest).encode(), *where, "manifest.json")
+            if not version:
+                self._write(json.dumps({"last_check": time.time()}).encode(), "state.json")
+        source = "remote" if checked or any(new for _, new in got) else "cache"
+        return manifest, [data.decode("utf-8") for data, _ in got], source
+
+    def load(self, extensions=(), version=None, strict=False):
+        """The runtime text, or None when nothing verified is available and strict is off."""
+        names = ["core"] + [e for e in extensions if e != "core"]
+        key = (tuple(names), version)
+        hit = self._memo.get(key)
+        if hit and (version or time.time() - hit[1] < self.ttl):
+            self.state.update(hit[2])
+            return hit[0]
+        try:
+            manifest, texts, source = self._load(names, version)
+            self.state["error"] = None
+        except Exception as err:                  # network, hash or parse failure
+            self.state["error"] = "%s: %s" % (type(err).__name__, err)
+            try:                                  # Last Known Good, never the network
+                where = ("versions", version) if version else ("latest",)
+                manifest = json.loads(self._read(*where, "manifest.json") or b"null")
+                texts = [self._get(manifest, n, where, False)[0].decode("utf-8") for n in names]
+                source = "cache"
+            except Exception:
+                if strict:
+                    raise LoaderError(self.state["error"])
+                self.state.update(loaded=False, source="none")
+                return None
+        self.state.update(loaded=True, source=source, version=manifest["version"],
+                          source_commit=manifest["source_commit"],
+                          last_check=self._last_check() or None)
+        text = "\n\n".join(texts)
+        if self.state["error"] is None:           # a fallback copy is re-checked next call
+            self._memo[key] = (text, time.time(), {k: self.state[k] for k in
+                                                    ("loaded", "source", "version", "source_commit")})
+        return text

ilang_protocol-1.0.0.dist-info/METADATA

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: ilang-protocol
+Version: 1.0.0
+Summary: The iLang loader: fetches the official iLang runtime, verifies it, caches it and puts it in front of any model's context. Don't learn iLang. Your AI should.
+Author: Long Quan Zhu
+License: MIT
+Project-URL: Homepage, https://ilang.ai
+Project-URL: Source, https://github.com/ilang-ai/ilang
+Project-URL: Specification, https://github.com/ilang-ai/ilang-spec
+Keywords: ilang,iLang,ai,llm,prompt,protocol,agent,openai,anthropic,gemini,deepseek
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ilang-protocol
+
+**Don't learn iLang. Your AI should.**
+
+The Python loader for [iLang](https://ilang.ai). It fetches the official iLang runtime from the canon repository, checks its sha256, keeps a verified copy on disk and adds it to any model's messages.
+
+```bash
+pip install ilang-protocol
+```
+
+```python
+import ilang
+
+messages = ilang.wrap([{"role": "user", "content": "帮我分析这个问题"}])   # OpenAI-style messages
+system = ilang.system()                                                     # Anthropic, Gemini
+print(ilang.status())
+```
+
+Updates are checked at most once an hour; without a network the last verified copy is used, and with no copy at all the messages go out unchanged unless `strict=True`. Pin an exact runtime with `version=` for reproducible runs; add `extensions=["media"]` for image, video and audio work. The core runtime is about 27,000 tokens, so enable your provider's prompt caching.
+
+Standard library only, Python 3.9+. Source, JavaScript version and documentation: [github.com/ilang-ai/ilang](https://github.com/ilang-ai/ilang). MIT.

ilang_protocol-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+ilang/__init__.py,sha256=nTuwdZ3TsCJhfOWnw3c_k-ypKTH0-pBwbDAq-IBjAzs,1957
+ilang/injector.py,sha256=-UdojndTbGoj79vg2mAx-H8NVHMdfM82gjuTr8CXOAY,1302
+ilang/loader.py,sha256=rgHRf9PICFcDJKIgfxYzo6kTsnFqu2kMFWaNcxdyY2U,5996
+ilang_protocol-1.0.0.dist-info/licenses/LICENSE,sha256=vUvmcq0vePRJr4bZeTst8b19WRx5qhI76vsRikBE61I,1065
+ilang_protocol-1.0.0.dist-info/METADATA,sha256=GwVcSDJwDGRF4Lrr8W_1iOYnlipy-cHpdRzP3aV7RGY,1855
+ilang_protocol-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ilang_protocol-1.0.0.dist-info/top_level.txt,sha256=RLdGVo0I4tboA7_R26lY_TdSW0I3nUpkgBsP7rWMro4,6
+ilang_protocol-1.0.0.dist-info/RECORD,,

ilang_protocol-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ilang_protocol-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ilang-ai
+
+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.

ilang_protocol-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ilang