bluesilk 0.1.0__tar.gz

bluesilk-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+.env
+__pycache__/
+dist/

bluesilk-0.1.0/LICENSE

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

bluesilk-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.5
+Name: bluesilk
+Version: 0.1.0
+Summary: A fast, minimal personal AI agent: DeepSeek + Telegram, zero dependencies.
+Project-URL: Repository, https://github.com/wunsiang-cheng/bluesilk
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# bluesilk
+
+A fast, minimal personal AI agent. DeepSeek + Telegram, one file, zero dependencies.
+
+1 key + 1 bot token + 1 user ID and you're good to go:
+
+```sh
+uv tool install bluesilk   # or: pipx install bluesilk
+bluesilk                   # first run asks for the three values, then starts
+bluesilk setup             # redo setup
+```
+
+- **Tools:** `shell` (unrestricted) and `send` (text/files to Telegram).
+- **Commands:** `/new` starts a new conversation; `/reset` returns to a fresh install (keys kept, old data moved to `~/.bluesilk.bak-<time>`).
+- **Images:** photos you send go straight to deepseek-flash vision.
+- **Feedback:** 👀 on receipt, a live status draft with a stop button, then the reply.
+- **Memory:** plain files in `~/.bluesilk/` (`MEMORY.md`, `memory/`, `skills/`, `tools/`), managed by the agent itself.
+- **Context:** compacted into a summary past 50% of the 1M window.
+- **Reflection:** after 24h, once idle for 30 min, it reviews history, tidies memory and writes new skills/tools.
+
+Keep it running with `tmux` or `nohup bluesilk &`.

bluesilk-0.1.0/README.md

@@ -0,0 +1,21 @@
+# bluesilk
+
+A fast, minimal personal AI agent. DeepSeek + Telegram, one file, zero dependencies.
+
+1 key + 1 bot token + 1 user ID and you're good to go:
+
+```sh
+uv tool install bluesilk   # or: pipx install bluesilk
+bluesilk                   # first run asks for the three values, then starts
+bluesilk setup             # redo setup
+```
+
+- **Tools:** `shell` (unrestricted) and `send` (text/files to Telegram).
+- **Commands:** `/new` starts a new conversation; `/reset` returns to a fresh install (keys kept, old data moved to `~/.bluesilk.bak-<time>`).
+- **Images:** photos you send go straight to deepseek-flash vision.
+- **Feedback:** 👀 on receipt, a live status draft with a stop button, then the reply.
+- **Memory:** plain files in `~/.bluesilk/` (`MEMORY.md`, `memory/`, `skills/`, `tools/`), managed by the agent itself.
+- **Context:** compacted into a summary past 50% of the 1M window.
+- **Reflection:** after 24h, once idle for 30 min, it reviews history, tidies memory and writes new skills/tools.
+
+Keep it running with `tmux` or `nohup bluesilk &`.

bluesilk-0.1.0/bluesilk.py

@@ -0,0 +1,485 @@
+"""bluesilk: a fast, minimal personal AI agent. DeepSeek + Telegram, stdlib only."""
+import base64, datetime, getpass, json, os, platform, queue, shutil, signal, subprocess, sys, threading, time, uuid
+from pathlib import Path
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+MODEL = "deepseek-flash"
+API = "https://api.deepseek.com"
+COMPACT_AT = 500_000  # 50% of deepseek-flash's 1M context
+SHELL_TIMEOUT = 600
+CLIP = 20_000  # long tool output keeps this many chars of head and tail
+DREAM_EVERY = 24 * 3600
+DREAM_IDLE = 30 * 60
+IMAGE_BUDGET = 20 * 2**20  # base64 chars of images kept in context; the API caps a request at 48 MiB
+IMAGE_SIGS = ((b"\xff\xd8\xff", "image/jpeg"), (b"\x89PNG", "image/png"), (b"GIF8", "image/gif"))  # WebP: see as_image
+
+HOME = Path(os.environ.get("BLUESILK_HOME", Path.home() / ".bluesilk"))
+CONFIG, STATE_FILE, HISTORY = HOME / "config.json", HOME / "state.json", HOME / "history.jsonl"
+
+CFG, STATE = {}, {}
+Q = queue.Queue()  # (text, message_id) for chat turns, None for a dream
+STOP, BUSY = threading.Event(), threading.Event()
+DRAFT = {"id": 0, "text": ""}
+LAST = {"active": time.time(), "prompt_tokens": 0}
+
+TOOLS = [
+    {"type": "function", "function": {
+        "name": "shell",
+        "description": "Run a bash command on the host. Unrestricted, no confirmation needed. stdin is closed; stdout+stderr "
+                       "are merged and clipped to head/tail. Background processes must redirect output: `cmd > log 2>&1 &`.",
+        "parameters": {"type": "object", "properties": {
+            "command": {"type": "string"},
+            "timeout": {"type": "integer", "description": f"seconds, default {SHELL_TIMEOUT}"}},
+            "required": ["command"]}}},
+    {"type": "function", "function": {
+        "name": "send",
+        "description": "Send the user a Telegram message and/or file right now (progress updates, files, proactive notices). "
+                       "Your final reply is delivered automatically; don't duplicate it here.",
+        "parameters": {"type": "object", "properties": {
+            "text": {"type": "string"},
+            "file": {"type": "string", "description": "path of a file to send"}}}}},
+]
+
+SYSTEM = """You are bluesilk, a personal AI agent chatting with its owner through Telegram. Be fast, direct and concise. Reply in the user's language.
+Environment: {os} as user {user}; shell cwd is {cwd}. Session started {now}.
+
+Tools: `shell` (unrestricted, never ask for permission, just do it) and `send`. Your final reply is delivered to Telegram automatically.
+Telegram Markdown only: *bold*, _italic_, `code`, ```block```. No headings, no tables.
+
+Your home is {home}:
+- MEMORY.md: core memory, included below. Keep it short.
+- memory/*.md: detailed memory by topic. grep/cat when relevant.
+- skills/*.md: how-tos. Read the matching skill before doing that kind of task.
+- tools/: scripts you wrote. Run them with shell.
+- inbox/: files the user sent you. Images (JPEG/PNG/GIF/WebP) are also attached to the message, so you see them directly.
+- history.jsonl: the full conversation log.
+
+Memory is your job and fully automatic: whenever you learn something durable (preferences, facts about the user, environment, projects, decisions, lessons from mistakes), write it to MEMORY.md or memory/<topic>.md right away, without asking or announcing it. Fix or delete entries that turn out wrong.
+
+## Skills
+{skills}
+
+## Tools
+{tools}
+
+## MEMORY.md
+{memory}"""
+
+REFLECT = """# reflect: review recent history, consolidate memory, turn repeated work into skills and tools
+Use when asked to reflect or dream, and on the periodic trigger.
+
+1. Read the new part of history.jsonl (the trigger gives the byte range; if it is big, read it in chunks).
+2. Consolidate memory:
+   - Add durable facts that were missed: preferences, facts about the user, environment, projects, decisions, lessons.
+   - Merge duplicates, resolve contradictions (newer wins), delete stale entries.
+   - Keep MEMORY.md under 100 lines: only what every conversation needs. Move details to memory/<topic>.md and leave a one-line pointer.
+3. Find repeated work: the same kind of task done twice or more, or a procedure that went wrong before.
+   - Judgment or procedure -> skills/<name>.md, first line `# <name>: <when to use it>`.
+   - Deterministic steps -> executable tools/<name>, second line `# <what it does, usage>`. chmod +x it and run it once to verify.
+   - Fix or delete skills and tools that are wrong or unused.
+4. If anything substantive changed, send the user a short summary. Otherwise stay silent.
+"""
+
+COMMANDS = [{"command": "new", "description": "Start a new conversation"},
+            {"command": "reset", "description": "Wipe memory, skills, tools and history (keeps keys)"}]
+
+COMPACT = ("The context is getting long. Write a summary that will replace the conversation so far: the user's goals, "
+           "key facts and decisions, the state of ongoing tasks, open questions and important file paths. "
+           "Dense but complete. Reply with the summary only.")
+
+
+def log(*a):
+    print(time.strftime("%H:%M:%S"), *a, flush=True)
+
+
+def quiet(f, *a, **k):
+    try:
+        return f(*a, **k)
+    except Exception as e:
+        log("ignored:", e)
+
+
+def http(url, payload=None, data=None, headers=None, timeout=60):
+    if payload is not None:
+        data = json.dumps(payload).encode()
+    try:
+        with urlopen(Request(url, data, {"Content-Type": "application/json", **(headers or {})}), timeout=timeout) as r:
+            return json.load(r)
+    except HTTPError as e:
+        e.msg = e.read().decode(errors="replace")[:500]  # surface the API's reason in str(e)
+        raise
+
+
+# --- DeepSeek
+
+def chat(messages, **extra):
+    for attempt in range(4):
+        try:
+            r = http(f"{API}/chat/completions", {"model": MODEL, "messages": messages, "tools": TOOLS, **extra},
+                     headers={"Authorization": f"Bearer {CFG['api_key']}"}, timeout=900)
+            LAST["prompt_tokens"] = r["usage"]["prompt_tokens"]
+            return r["choices"][0]["message"]
+        except OSError as e:  # network errors, timeouts, HTTP errors
+            code = getattr(e, "code", 500)
+            if attempt == 3 or 400 <= code < 500 and code != 429:
+                raise
+            log("retrying:", e)
+            time.sleep(5 * 2 ** attempt)
+
+
+# --- Telegram
+
+def tg_url(method):
+    return f"https://api.telegram.org/bot{CFG['bot_token']}/{method}"
+
+
+def tg(method, **params):
+    return http(tg_url(method), params, timeout=70)["result"]
+
+
+def send_text(text):
+    for i in range(0, len(text), 4096):
+        chunk = text[i:i + 4096]
+        try:
+            tg("sendMessage", chat_id=CFG["user_id"], text=chunk, parse_mode="Markdown")
+        except HTTPError as e:
+            if e.code != 400:
+                raise
+            tg("sendMessage", chat_id=CFG["user_id"], text=chunk)  # the model's Markdown didn't parse
+
+
+def send_file(path):
+    path = Path(path).expanduser()
+    quiet(tg, "sendChatAction", chat_id=CFG["user_id"], action="upload_document")
+    b = uuid.uuid4().hex
+    head = (f'--{b}\r\nContent-Disposition: form-data; name="chat_id"\r\n\r\n{CFG["user_id"]}\r\n'
+            f'--{b}\r\nContent-Disposition: form-data; name="document"; filename="{path.name.replace(chr(34), "")}"\r\n\r\n')
+    body = head.encode() + path.read_bytes() + f"\r\n--{b}--\r\n".encode()
+    http(tg_url("sendDocument"), data=body, headers={"Content-Type": f"multipart/form-data; boundary={b}"}, timeout=600)
+
+
+def download(file):
+    fp = tg("getFile", file_id=file["file_id"])["file_path"]
+    dest = HOME / "inbox" / f"{int(time.time())}_{Path(file.get('file_name') or fp).name}"
+    with urlopen(f"https://api.telegram.org/file/bot{CFG['bot_token']}/{fp}", timeout=300) as r:
+        dest.write_bytes(r.read())
+    return dest
+
+
+def draft(text=None):
+    """Live status under the user's message: empty text shows Telegram's "Thinking..." placeholder."""
+    if text is not None:
+        DRAFT["text"] = text[:300]
+    if DRAFT["id"]:
+        quiet(tg, "sendMessageDraft", chat_id=CFG["user_id"], draft_id=DRAFT["id"], text=DRAFT["text"], can_stop=True)
+
+
+def heartbeat():
+    while True:  # drafts vanish after 30s
+        time.sleep(20)
+        draft()
+
+
+# --- tools
+
+def clip(s):
+    return s if len(s) <= 2 * CLIP else f"{s[:CLIP]}\n\n[... {len(s) - 2 * CLIP} chars omitted ...]\n\n{s[-CLIP:]}"
+
+
+def shell(command, timeout=SHELL_TIMEOUT):
+    # ponytail: POSIX only (process groups), Windows would need taskkill /T
+    p = subprocess.Popen(command, shell=True, executable=shutil.which("bash"), cwd=Path.home(), text=True, errors="replace",
+                         stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, start_new_session=True)
+    deadline = time.time() + int(timeout)
+    while True:
+        try:
+            out = p.communicate(timeout=1)[0]
+            break
+        except subprocess.TimeoutExpired:
+            if STOP.is_set() or time.time() > deadline:
+                os.killpg(p.pid, signal.SIGKILL)
+                out = p.communicate()[0] + ("\n[stopped by user]" if STOP.is_set() else f"\n[killed after {timeout}s]")
+                break
+    return clip(f"exit {p.returncode}\n{out}")
+
+
+def send(text="", file=""):
+    if text:
+        send_text(text)
+    if file:
+        send_file(file)
+    return "sent"
+
+
+def call_tool(c):
+    try:
+        args = json.loads(c["function"]["arguments"] or "{}")
+        draft(f"🔧 {args.get('command') or c['function']['name']}")
+        return {"shell": shell, "send": send}[c["function"]["name"]](**args)
+    except Exception as e:
+        return f"error: {e!r}"
+
+
+# --- agent
+
+def system_prompt():
+    first = lambda p, i: (p.read_text(errors="replace").splitlines()[i:i + 1] or [""])[0].lstrip("# ")
+    skills = "\n".join(f"- skills/{p.name}: {first(p, 0)}" for p in sorted((HOME / "skills").glob("*.md")))
+    tools = "\n".join(f"- tools/{p.name}: {first(p, 1)}" for p in sorted((HOME / "tools").iterdir()) if p.is_file())
+    text = SYSTEM.format(os=platform.platform(), user=getpass.getuser(), cwd=Path.home(), home=HOME,
+                         now=datetime.datetime.now().astimezone().isoformat(timespec="minutes"),
+                         skills=skills or "(none)", tools=tools or "(none)", memory=(HOME / "MEMORY.md").read_text())
+    if STATE.get("summary"):
+        text += f"\n\n## Summary of the earlier conversation\n{STATE['summary']}"
+    return text
+
+
+def add(messages, msg, record):
+    messages.append(msg)  # as returned: reasoning_content must be sent back when tools are in play
+    if record:
+        with HISTORY.open("a") as f:
+            entry = {"t": int(time.time()), **{k: v for k, v in msg.items() if k != "reasoning_content"}}
+            if isinstance(entry.get("content"), list):  # no base64 in the log; the text part has the file path
+                entry["content"] = "\n".join(p.get("text", "[image]") for p in entry["content"])
+            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+
+def run(messages, record):
+    # ponytail: compaction only between turns, a single turn past 1M tokens will fail
+    while True:
+        draft("")
+        msg = chat(messages)
+        add(messages, msg, record)
+        calls = msg.get("tool_calls")
+        if not calls:
+            return msg.get("content") or ""
+        for c in calls:  # every tool_call needs a reply, even when stopped
+            log("tool:", c["function"]["arguments"][:200])
+            result = "[stopped by user]" if STOP.is_set() else call_tool(c)
+            add(messages, {"role": "tool", "tool_call_id": c["id"], "content": result}, record)
+        if STOP.is_set():
+            return "⏹ stopped"
+
+
+def trim_images(messages):
+    budget = IMAGE_BUDGET
+    for m in reversed(messages):
+        for p in m["content"] if isinstance(m.get("content"), list) else []:
+            if p["type"] == "image_url" and (budget := budget - len(p["image_url"]["url"])) < 0:
+                p.clear()
+                p.update(type="text", text="[image dropped from context; the file is still in inbox/]")
+
+
+def chat_turn(content, message_id):
+    STOP.clear()
+    DRAFT["id"] = message_id
+    n = len(STATE["messages"])
+    add(STATE["messages"], {"role": "user", "content": content}, True)
+    trim_images(STATE["messages"])
+    try:
+        reply = run(STATE["messages"], True)
+    except HTTPError as e:
+        if e.code == 400:  # a rejected request (e.g. an unreadable image) would fail every later turn too
+            del STATE["messages"][n:]
+        raise
+    finally:
+        DRAFT["id"] = 0
+    send_text(reply or "✅")
+    if LAST["prompt_tokens"] > COMPACT_AT:
+        compact()
+
+
+def compact():
+    log("compacting at", LAST["prompt_tokens"], "tokens")
+    STATE["summary"] = chat(STATE["messages"] + [{"role": "user", "content": COMPACT}], tool_choice="none")["content"]
+    STATE["messages"] = [{"role": "system", "content": system_prompt()}]
+
+
+def dream():
+    size = HISTORY.stat().st_size if HISTORY.exists() else 0
+    start = STATE["history_offset"]
+    if size > start:
+        log("dreaming over", size - start, "bytes")
+        STOP.clear()
+        run([{"role": "system", "content": system_prompt()},
+             {"role": "user", "content": f"Periodic reflection: follow skills/reflect.md. New history is bytes {start}-{size}: "
+                                         f"`tail -c +{start + 1} {HISTORY} | head -c {size - start}`. "
+                                         "Your final reply here is NOT delivered; use send only if something substantive changed."}],
+            False)
+        STATE["messages"][0] = {"role": "system", "content": system_prompt()}  # pick up new memory, skills, tools
+    STATE.update(last_dream=time.time(), history_offset=size)
+
+
+def new_chat():
+    STATE.update(summary="", messages=[{"role": "system", "content": system_prompt()}])
+    send_text("🆕 New conversation")
+
+
+def reset():
+    backup = HOME.with_name(f"{HOME.name}.bak-{time.strftime('%Y%m%d-%H%M%S')}")
+    backup.mkdir(mode=0o700)
+    for p in HOME.iterdir():
+        if p != CONFIG:
+            p.rename(backup / p.name)  # moved, not deleted: a mis-tap is recoverable
+    init_home()
+    STATE.clear()
+    STATE.update(last_dream=time.time(), history_offset=0, messages=[{"role": "system", "content": system_prompt()}])
+    send_text(f"♻️ Reset to a fresh install. Old data: {backup}")
+
+
+def save():
+    tmp = STATE_FILE.with_suffix(".tmp")
+    tmp.write_text(json.dumps(STATE, ensure_ascii=False))
+    tmp.replace(STATE_FILE)
+
+
+def worker():
+    while True:
+        item = Q.get()
+        BUSY.set()
+        try:
+            if item is None:
+                dream()
+            elif item == "/new":
+                new_chat()
+            elif item == "/reset":
+                reset()
+            else:
+                chat_turn(*item)
+        except Exception as e:
+            log("error:", repr(e))
+            quiet(send_text, f"⚠️ {e}")
+        finally:
+            BUSY.clear()
+            LAST["active"] = time.time()
+            save()
+
+
+def as_image(path):
+    """data: URI if DeepSeek can read the file as an image. It sniffs content, not names, so do we."""
+    data = path.read_bytes()
+    mime = next((t for sig, t in IMAGE_SIGS if data.startswith(sig)), "image/webp" if data[8:12] == b"WEBP" else None)
+    return mime and f"data:{mime};base64,{base64.b64encode(data).decode()}"
+
+
+def incoming(m):
+    parts, images = [], []
+    for kind in ("document", "photo", "audio", "video", "voice", "video_note", "animation"):
+        if f := m.get(kind):
+            try:
+                path = download(f[-1] if kind == "photo" else f)
+                parts.append(f"[file saved: {path}]")
+                images += filter(None, [as_image(path)])
+            except Exception as e:
+                parts.append(f"[{kind} download failed: {e}]")
+    text = "\n".join(parts + [m.get("text") or m.get("caption") or ""]).strip()
+    return [{"type": "text", "text": text}, *({"type": "image_url", "image_url": {"url": u}} for u in images)] if images else text
+
+
+def handle_update(u):
+    if "stopped_message_generation" in u:
+        STOP.set()
+        return
+    m = u.get("message")
+    if not m or m.get("from", {}).get("id") != CFG["user_id"]:  # the only trust boundary: owner only
+        return
+    quiet(tg, "setMessageReaction", chat_id=CFG["user_id"], message_id=m["message_id"],
+          reaction=[{"type": "emoji", "emoji": "👀"}])
+    LAST["active"] = time.time()
+    if m.get("text") in ("/new", "/reset"):
+        STOP.set()  # interrupt whatever is running, then the worker handles the command in order
+        Q.put(m["text"])
+    else:
+        Q.put((incoming(m), m["message_id"]))
+
+
+def dream_due(now):
+    return (not BUSY.is_set() and Q.empty() and now - LAST["active"] > DREAM_IDLE
+            and now - STATE["last_dream"] > DREAM_EVERY)
+
+
+def init_home():
+    for d in ("memory", "skills", "tools", "inbox"):
+        (HOME / d).mkdir(parents=True, exist_ok=True)
+    (HOME / "MEMORY.md").touch()
+    if not (HOME / "skills" / "reflect.md").exists():
+        (HOME / "skills" / "reflect.md").write_text(REFLECT)
+
+
+def serve():
+    CFG.update(json.loads(CONFIG.read_text()))
+    init_home()
+    if STATE_FILE.exists():
+        STATE.update(json.loads(STATE_FILE.read_text()))
+    STATE.setdefault("last_dream", time.time())
+    STATE.setdefault("history_offset", 0)
+    STATE.setdefault("messages", [None])[0] = {"role": "system", "content": system_prompt()}  # fresh memory/skills per start
+    threading.Thread(target=worker, daemon=True).start()
+    threading.Thread(target=heartbeat, daemon=True).start()
+    log(f"bluesilk running as @{tg('getMe')['username']}, Ctrl+C to stop")
+    quiet(tg, "setMyCommands", commands=COMMANDS, scope={"type": "chat", "chat_id": CFG["user_id"]})
+    quiet(tg, "sendMessage", chat_id=CFG["user_id"], text="🟢 bluesilk online")
+    offset = 0
+    while True:
+        try:
+            for u in tg("getUpdates", offset=offset, timeout=50, allowed_updates=["message", "stopped_message_generation"]):
+                offset = u["update_id"] + 1
+                handle_update(u)
+        except Exception as e:
+            log("poll error:", e)
+            time.sleep(5)
+        if dream_due(time.time()):
+            LAST["active"] = time.time()
+            Q.put(None)
+
+
+# --- setup
+
+def ask(prompt, check, secret=False):
+    while True:
+        value = (getpass.getpass if secret else input)(f"{prompt}: ").strip().strip("\"'")
+        try:
+            check(value)
+            return value
+        except Exception as e:
+            print(f"  ✗ {e}")
+
+
+def setup():
+    print("bluesilk setup: 1 key + 1 bot token + 1 user ID\n")
+
+    def check_key(v):
+        http(f"{API}/models", headers={"Authorization": f"Bearer {v}"})
+        print("  ✓ DeepSeek key works")
+
+    def check_token(v):
+        CFG["bot_token"] = v
+        print(f"  ✓ bot @{tg('getMe')['username']}")
+
+    def check_user(v):
+        CFG["user_id"] = int(v)
+        tg("sendChatAction", chat_id=CFG["user_id"], action="typing")  # fails until the user has pressed Start
+        print("  ✓ bot can reach you")
+
+    CFG["api_key"] = ask("DeepSeek API key (platform.deepseek.com/api_keys)", check_key, secret=True)
+    ask("Telegram bot token (from @BotFather)", check_token, secret=True)
+    ask("Your Telegram user ID (ask @userinfobot; press Start on your bot first)", check_user)
+    HOME.mkdir(mode=0o700, parents=True, exist_ok=True)
+    CONFIG.touch(mode=0o600)
+    CONFIG.chmod(0o600)
+    CONFIG.write_text(json.dumps(CFG))
+    print(f"\nSaved to {CONFIG}. Starting...\n")
+
+
+def main():
+    try:
+        if sys.argv[1:2] == ["setup"] or not CONFIG.exists():
+            setup()
+        serve()
+    except (KeyboardInterrupt, EOFError):
+        print()
+
+
+if __name__ == "__main__":
+    main()

bluesilk-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "bluesilk"
+version = "0.1.0"
+description = "A fast, minimal personal AI agent: DeepSeek + Telegram, zero dependencies."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/wunsiang-cheng/bluesilk"
+
+[project.scripts]
+bluesilk = "bluesilk:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+only-include = ["bluesilk.py"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["bluesilk.py", "test_bluesilk.py", "README.md", "LICENSE"]  # never ship .env

bluesilk-0.1.0/test_bluesilk.py

@@ -0,0 +1,149 @@
+"""Offline self-check: python test_bluesilk.py"""
+import json, os, tempfile, time
+
+os.environ["BLUESILK_HOME"] = tempfile.mkdtemp()
+import bluesilk as b
+
+sent = []
+b.tg = lambda method, **p: sent.append((method, p)) or {"file_path": "photos/x.jpg", "username": "bot"}
+b.CFG.update(api_key="k", bot_token="t", user_id=42)
+b.init_home()
+b.STATE.update(last_dream=time.time(), history_offset=0, messages=[{"role": "system", "content": b.system_prompt()}])
+
+
+def script(*replies, tokens=100, on_call=None):
+    replies = list(replies)
+    def chat(messages, **extra):
+        b.LAST["prompt_tokens"] = tokens
+        on_call and on_call()
+        return replies.pop(0)
+    b.chat = chat
+
+
+def call(i, cmd):
+    return {"id": f"c{i}", "type": "function", "function": {"name": "shell", "arguments": json.dumps({"command": cmd})}}
+
+
+# clip keeps head and tail
+assert b.clip("x" * 10) == "x" * 10
+s = b.clip("a" * b.CLIP + "m" * 50 + "z" * b.CLIP)
+assert s.startswith("a") and s.endswith("z") and "50 chars omitted" in s
+
+# shell: exit code, merged output, closed stdin, timeout kills the whole process group
+assert b.shell("echo hi; echo err >&2; exit 3") == "exit 3\nhi\nerr\n"
+assert b.shell("cat").startswith("exit 0")
+t = time.time()
+assert "killed after 1s" in b.shell("sleep 30 | cat", timeout=1) and time.time() - t < 5
+
+# agent loop: tool call -> result -> final reply; reasoning kept in context, not in history
+script({"role": "assistant", "content": "", "reasoning_content": "r1", "tool_calls": [call(1, "echo hello")]},
+       {"role": "assistant", "content": "done", "reasoning_content": "r2"})
+b.chat_turn("hi", 7)
+msgs = b.STATE["messages"]
+assert [m["role"] for m in msgs] == ["system", "user", "assistant", "tool", "assistant"]
+assert msgs[2]["reasoning_content"] == "r1" and "hello" in msgs[3]["content"]
+assert sent[-1] == ("sendMessage", {"chat_id": 42, "text": "done", "parse_mode": "Markdown"})
+assert any(m == "sendMessageDraft" and p["draft_id"] == 7 and p["text"] == "🔧 echo hello" for m, p in sent)
+assert b.DRAFT["id"] == 0
+assert "reasoning_content" not in b.HISTORY.read_text() and b.HISTORY.read_text().count("\n") == 4
+
+# stop: every pending tool_call still gets a reply
+script({"role": "assistant", "content": "", "tool_calls": [call(2, "touch /tmp/should-not"), call(3, "true")]},
+       on_call=b.STOP.set)
+b.chat_turn("go", 8)
+assert [m["content"] for m in b.STATE["messages"][-2:]] == ["[stopped by user]"] * 2
+assert sent[-1][1]["text"] == "⏹ stopped"
+
+# compaction past 50%: context becomes system prompt + summary
+script({"role": "assistant", "content": "big"}, {"role": "assistant", "content": "SUMMARY"}, tokens=b.COMPACT_AT + 1)
+b.chat_turn("more", 9)
+assert len(b.STATE["messages"]) == 1 and "SUMMARY" in b.STATE["messages"][0]["content"]
+
+# updates: strangers ignored, owner gets 👀 and is queued, stop button sets STOP
+b.STOP.clear()
+b.handle_update({"message": {"message_id": 1, "from": {"id": 666}, "text": "hack"}})
+assert b.Q.empty()
+b.handle_update({"message": {"message_id": 2, "from": {"id": 42}, "caption": "look", "photo": [{"file_id": "s"}, {"file_id": "L"}]}})
+assert [m for m, _ in sent[-2:]] == ["setMessageReaction", "getFile"]  # 👀 before the download
+text, mid = b.Q.get_nowait()
+assert mid == 2 and text.endswith("look") and "[" in text  # download attempted (fails offline, noted inline)
+b.handle_update({"update_id": 3, "stopped_message_generation": {}})
+assert b.STOP.is_set()
+
+# images: detected by content, attached for vision, kept out of history
+shot = b.HOME / "inbox" / "shot"
+shot.write_bytes(b"\x89PNG\r\n\x1a\n" + b"0" * 100)
+b.download = lambda f: shot
+b.handle_update({"message": {"message_id": 4, "from": {"id": 42}, "caption": "what is this", "document": {"file_id": "d"}}})
+content, _ = b.Q.get_nowait()
+assert content[0] == {"type": "text", "text": f"[file saved: {shot}]\nwhat is this"}
+assert content[1]["image_url"]["url"].startswith("data:image/png;base64,")
+fake = b.HOME / "inbox" / "notes.png"
+fake.write_text("not an image")
+b.download = lambda f: fake
+b.handle_update({"message": {"message_id": 5, "from": {"id": 42}, "document": {"file_id": "d"}}})
+assert isinstance(b.Q.get_nowait()[0], str)
+script({"role": "assistant", "content": "a png"})
+b.chat_turn(content, 10)
+assert "base64" not in b.HISTORY.read_text() and "what is this" in b.HISTORY.read_text()
+
+# oldest images leave the context first once over budget
+img = lambda n: {"role": "user", "content": [{"type": "text", "text": "t"}, {"type": "image_url", "image_url": {"url": "x" * n}}]}
+b.IMAGE_BUDGET, msgs = 100, [img(60), img(50)]
+b.trim_images(msgs)
+assert msgs[1]["content"][1]["type"] == "image_url" and msgs[0]["content"][1]["type"] == "text"
+
+# a request the API rejects (bad image, ...) is rolled back so it can't poison later turns
+def reject(messages, **extra):
+    raise b.HTTPError("u", 400, "bad image", {}, None)
+b.chat, n = reject, len(b.STATE["messages"])
+try:
+    b.chat_turn("poison", 11)
+    raise AssertionError("expected HTTPError")
+except b.HTTPError:
+    pass
+assert len(b.STATE["messages"]) == n
+
+# dream: due only when idle and old enough; consumes history silently
+b.BUSY.clear()
+b.LAST["active"] = time.time() - b.DREAM_IDLE - 1
+assert not b.dream_due(time.time())
+b.STATE["last_dream"] = 0
+assert b.dream_due(time.time())
+n = len(sent)
+script({"role": "assistant", "content": "nothing new"})
+b.dream()
+assert b.STATE["history_offset"] == b.HISTORY.stat().st_size and b.STATE["last_dream"] > 0
+assert not any(m == "sendMessage" for m, _ in sent[n:])
+
+# multipart upload carries the file bytes
+f = b.HOME / "inbox" / "report.txt"
+f.write_bytes(b"\x00payload")
+captured = {}
+b.http = lambda url, **k: captured.update(url=url, **k)
+b.send_file(f)
+assert captured["url"].endswith("/sendDocument") and b"\x00payload" in captured["data"]
+assert b'filename="report.txt"' in captured["data"] and "boundary=" in captured["headers"]["Content-Type"]
+
+# commands: interrupt the running turn and go through the worker queue
+b.STOP.clear()
+b.handle_update({"message": {"message_id": 30, "from": {"id": 42}, "text": "/reset"}})
+assert b.STOP.is_set() and b.Q.get_nowait() == "/reset"
+
+# /new: fresh context, fresh system prompt
+b.STATE.update(summary="old", messages=[{"role": "system", "content": "stale"}, {"role": "user", "content": "x"}])
+b.new_chat()
+assert len(b.STATE["messages"]) == 1 and b.STATE["messages"][0]["content"] != "stale" and not b.STATE["summary"]
+
+# /reset: everything but config moves to a backup, home is back to a fresh install
+b.CONFIG.write_text("{}")
+(b.HOME / "skills" / "mine.md").write_text("# mine: custom")
+(b.HOME / "MEMORY.md").write_text("secret fact")
+b.reset()
+backup = next(b.HOME.parent.glob(b.HOME.name + ".bak-*"))
+assert b.CONFIG.exists() and (backup / "skills" / "mine.md").exists() and (backup / "history.jsonl").exists()
+assert [p.name for p in (b.HOME / "skills").iterdir()] == ["reflect.md"] and (b.HOME / "MEMORY.md").read_text() == ""
+assert not b.HISTORY.exists() and b.STATE["history_offset"] == 0 and "secret fact" not in b.STATE["messages"][0]["content"]
+assert sent[-1][1]["text"].startswith("♻️")
+
+print("ok")