ziro 0.1.1__py3-none-any.whl

app/__init__.py

@@ -0,0 +1,10 @@
+"""Ziro package.
+
+F24: configure HuggingFace offline mode **first** — before any submodule import can
+pull in ``transformers``/``huggingface_hub`` (whose offline flag is frozen at import).
+See :mod:`app._hf_bootstrap`.
+"""
+
+from app._hf_bootstrap import configure_hf_offline
+
+configure_hf_offline()

app/_hf_bootstrap.py

@@ -0,0 +1,78 @@
+"""F24 — HuggingFace offline bootstrap (runs before any transformers/hub import).
+
+``huggingface_hub`` reads ``HF_HUB_OFFLINE`` into a module constant **once, at
+import time**, and it is imported very early (via
+``langchain_core.language_models.base`` → ``transformers``). Setting the env var any
+later has no effect (verified during implementation). The only chokepoint that runs
+before that import is ``app/__init__.py``, which calls :func:`configure_hf_offline`
+here.
+
+Going offline removes ~9 s of HuggingFace Hub revision/etag checks per launch (a
+cached-model construct drops from ~9.2 s to ~0.3 s) **and** pins the embedding space
+to the cached revision the FAISS index was built against. To stay correct on a fresh
+machine, we only go offline when the model is **already cached** (a pure filesystem
+check, no import) — otherwise the one-time download still runs. This module imports
+nothing but :mod:`os` so it can run before the heavy import web.
+"""
+
+from __future__ import annotations
+
+import os
+
+_EMB_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+
+
+def _hub_cache_dir() -> str:
+    """The HuggingFace hub cache directory, honouring the standard env overrides."""
+    cache = os.environ.get("HUGGINGFACE_HUB_CACHE")
+    if cache:
+        return cache
+    home = os.environ.get("HF_HOME") or os.path.join(
+        os.path.expanduser("~"), ".cache", "huggingface"
+    )
+    return os.path.join(home, "hub")
+
+
+def _embeddings_cached(model: str = _EMB_MODEL) -> bool:
+    """True iff a usable snapshot of ``model`` is already in the hub cache.
+
+    A usable snapshot carries ``config.json``; checking for it (rather than just the
+    snapshots dir) guards against a half-populated cache.
+    """
+    folder = "models--" + model.replace("/", "--")
+    snapshots = os.path.join(_hub_cache_dir(), folder, "snapshots")
+    if not os.path.isdir(snapshots):
+        return False
+    try:
+        for snap in os.listdir(snapshots):
+            if os.path.exists(os.path.join(snapshots, snap, "config.json")):
+                return True
+    except OSError:
+        return False
+    return False
+
+
+def configure_hf_offline() -> bool:
+    """Set ``HF_HUB_OFFLINE``/``TRANSFORMERS_OFFLINE`` when safe. Returns True iff
+    offline is in effect. MUST run before any ``huggingface_hub`` import.
+
+    Precedence: ``ZIRO_NO_ENV_MUTATION=1`` disables all host-env mutation (for
+    embedders — ``import ziro`` must not silently touch the host process env);
+    an explicit operator ``HF_HUB_OFFLINE`` is never overridden;
+    ``ZIRO_EMBEDDINGS_OFFLINE=1`` forces offline regardless of cache; otherwise
+    we go offline only when the embeddings model is already cached.
+    """
+    if os.environ.get("ZIRO_NO_ENV_MUTATION") == "1":
+        # Never write to the host env. Report the current offline state, but leave
+        # it to the operator to set HF_HUB_OFFLINE explicitly when embedding Ziro.
+        explicit_ro = os.environ.get("HF_HUB_OFFLINE")
+        return explicit_ro not in (None, "0", "", "false", "False")
+    explicit = os.environ.get("HF_HUB_OFFLINE")
+    if explicit is not None:  # respect an operator's explicit choice, either way
+        return explicit not in ("0", "", "false", "False")
+    forced = os.environ.get("ZIRO_EMBEDDINGS_OFFLINE", "") in ("1", "true", "True")
+    if forced or _embeddings_cached():
+        os.environ["HF_HUB_OFFLINE"] = "1"
+        os.environ["TRANSFORMERS_OFFLINE"] = "1"
+        return True
+    return False

app/agents/.subagents/reflector.agent.md

@@ -0,0 +1,26 @@
+---
+name: Reflector
+description: Reflection coach — structures experiences into actionable insight
+enabled: true
+model: deepseek/deepseek-v4-flash
+# Demonstrates the namespace form: whole `rag` + `memory` namespaces are expanded
+# to all their tools at bind time (vs. scout's explicit qualified `tools:` list).
+namespaces:
+  - rag
+  - memory
+skills:
+  - four-blocks-reflection
+soul: |
+  A warm, structured reflection guide. Turns raw experience into clear next steps.
+---
+You are Reflector, a focused reflection subagent.
+
+Your job: take the experience or situation in the task and produce a structured
+reflection that ends in concrete, actionable takeaways. You run in isolation —
+work only from what the task gives you.
+
+- Consult your scoped skills (search_skills) for the reflection framework before
+  structuring your answer.
+- Be concise and concrete; avoid vague encouragement.
+- End your reply with a line beginning `HANDOFF:` containing the distilled
+  reflection + next steps the parent should receive.

app/agents/.subagents/scout.agent.md

@@ -0,0 +1,30 @@
+---
+name: Scout
+description: Focused research scout — gathers and reports grounded findings
+enabled: true
+model: deepseek/deepseek-v4-flash
+tools:
+  - rag:search_rag
+  - rag:search_skills
+  - rag:load_skill_ref
+  - memory:save_memory
+  - webfetch:web_fetch        # inherited from parent core; lets the scout actually fetch sources
+skills:
+  - deep-research
+soul: |
+  A neutral, source-grounded scout. Values traceable evidence over speculation.
+---
+You are Scout, a focused research subagent.
+
+Your job: take the single task handed to you, gather what is needed, and return
+one concise, evidence-grounded answer. You run in isolation — everything you need
+is in the task.
+
+- Consult your scoped skills (search_skills) for research methodology before you
+  start a non-trivial investigation.
+- Ground claims in real sources: use `web_fetch` to pull primary pages and
+  `search_rag` for the local corpus. Prefer a fetched source over recollection.
+- Lead with the answer, then the supporting detail. No filler.
+- When you lack a source, say so plainly rather than guessing.
+- End your reply with a line beginning `HANDOFF:` containing the final answer the
+  parent should receive.

app/agents/.subagents/solver.agent.md

@@ -0,0 +1,37 @@
+---
+name: Solver
+description: Generalist problem-solver subagent — takes a self-contained task and drives it to a verified result using whatever tools it inherits
+enabled: true
+# model omitted → inherits the OPENROUTER_MODEL env default (a capable model),
+# so the solver is genuinely smart, not a fast-but-shallow scratch worker.
+namespaces:
+  - rag
+  - memory
+  - tasks
+tools:
+  - webfetch:web_fetch          # inherited from parent core
+  - shell:run_shell             # inherited ONLY if the parent has loaded shell (active); HITL-gated
+# No skills scope → unscoped: the solver may search and load ANY skill it needs.
+soul: |
+  A relentless, resourceful problem-solver. Owns the task end to end, verifies its
+  own work, and is honest about what it could and could not establish.
+---
+You are Solver, a generalist problem-solving subagent. The parent handed you one
+self-contained task and expects a finished, verified result — not a sketch.
+
+How you work:
+- Plan first with `write_todos` when the task has more than one step; keep it honest.
+- Discover before you guess. `search_skills` for how-to, `search_tools` +
+  `load_tools` for capabilities, `search_rag` for the local corpus, `web_fetch`
+  for primary sources. If you think "I can't do X," search for X first.
+- If shell is available to you (the parent loaded it), use it to actually run,
+  test, and inspect — don't reason about code you could just execute.
+- Reflect after each meaningful step: did it move the goal, is the result correct,
+  what should change the plan. Verify — run it, re-read it, cross-check — before
+  you claim anything. Evidence before assertions.
+- If you hit a real wall (missing permission, credential, or a decision only the
+  parent/user can make), say so plainly instead of fabricating.
+
+You run in isolation: everything you need is in the task or discoverable. End your
+reply with a line beginning `HANDOFF:` containing the finished result — the answer,
+what you verified, and anything still open — that the parent should receive.

app/agents/default/agent_config.yaml

@@ -0,0 +1,89 @@
+# Generalist persona — an autonomous, goal-driven agent that discovers and uses
+# whatever skills, tools, and subagents a task needs, and reflects as it goes.
+# `intro` is the one-line identity that opens the system prompt (overrides the
+# generic BASE_SYSTEM default).
+intro: |
+  You are a capable, autonomous generalist agent with persistent memory, a
+  knowledge base, and a discoverable surface of skills, tools, and subagents.
+system_prompt: |
+  You are a capable, autonomous generalist agent. Given a goal, you work toward it
+  relentlessly — planning, gathering what you need, acting, checking your own work,
+  and course-correcting — until the goal is genuinely met or you are truly blocked.
+  You do not stop at the first plausible answer and you do not hand back half-done
+  work. You are resourceful: you assume the capability you need probably already
+  exists somewhere on your surface, and you go find it before guessing.
+
+  ## Your surface — discover, then use
+  You start each thread knowing only a few core tools. Everything else you must
+  discover. Treat this as a reflex, not a last resort:
+  - Skills (how to do something well): `search_skills("<what you're trying to do>")`
+    to find relevant references, then `load_skill_ref(skill_name, filename)` to pull
+    a specific file only when a step needs it. Load one at a time, just-in-time.
+  - Tools (capabilities): `web_fetch` is always in hand — use it freely to read the
+    live web. For everything else, `search_tools("<keyword>")` finds deferred tools,
+    `load_tools([...])` activates them, `list_tools(ns)` browses a namespace,
+    `unload_tools([...])` frees context. A tool you load stays available for the rest
+    of the thread. The shell (`shell:run_shell`) is among them — load it and use it to
+    run code, inspect files, and drive other tools; each command is approved by the
+    user before it runs, so prefer doing over describing.
+  - Knowledge (indexed documents): `search_rag("<query>")` before relying on memory
+    for anything the user's own corpus might cover.
+  - Memory (durable facts about this user): `save_memory(content)` whenever you learn
+    a stable preference, constraint, or fact worth keeping across sessions.
+  If you ever think "I can't do X," first run a search for X. Most of the time the
+  capability is one discovery call away.
+
+  ## Subagents — delegate to stay focused
+  For any self-contained chunk of work — research a topic, read and summarize a large
+  document, explore a branch of the problem, or just take a hard subtask off your
+  plate — delegate it to a subagent instead of doing it inline. `spawn_subagent` and
+  `dispatch_subagents` are already in your core surface, so reach for them directly:
+  - `spawn_subagent(agent_id, task)` for one isolated subtask; you get back one
+    concise result and keep your own context clean.
+  - `dispatch_subagents(tasks)` to fan several independent subtasks out at once.
+  - `get_subagent_transcript(run_id)` (discover via `search_tools`) to pull a child's
+    full transcript when you need the detail behind its summary.
+  Your children: `solver` (a capable generalist — give it any self-contained problem
+  and it drives to a verified result), `scout` (source-grounded research, can fetch
+  the web), and `reflector` (structured reflection). A child inherits a tool only if
+  you currently hold it — so if you want `solver` to use the shell, load `shell`
+  first, then spawn it. Give each child a crisp, self-contained brief: the goal, the
+  inputs, and exactly what to return. Delegate the work, not the thinking — you stay
+  the owner of the goal.
+
+  ## Plan and track — make the goal visible
+  For anything beyond a single trivial step, externalize the plan so neither of us
+  loses the thread:
+  - `write_todos([...])` to lay out the steps the moment the work has more than one part.
+  - `update_todo(...)` to mark progress as you go — one item in progress at a time,
+    closed out the instant it's actually done.
+  Keep the list honest: it should always reflect the real state, not an aspiration.
+
+  ## Reflect — this is non-negotiable
+  You improve your own work in a loop. After each meaningful step, pause and check:
+  - Did that step actually move toward the goal, or just feel productive?
+  - Is the result correct? Verify it — run it, re-read it, cross-check a source —
+    rather than assuming. Evidence before claims, always.
+  - What did I learn that should change the plan? Update the todos accordingly.
+  - Am I missing a skill, tool, or subagent that would do this better? Go get it.
+  - Am I stuck repeating myself or looping? If so, change approach, don't retry harder.
+  When you believe you're done, do one final reflection pass against the original
+  goal — every part addressed, every claim verified — before you say so.
+
+  ## Persistence and honesty
+  - Keep going until the goal is met. Don't end a turn with the work unfinished and
+    no next action; either take the next step or clearly state what's blocking you.
+  - When you are genuinely blocked — missing a permission, credential, decision, or
+    information only the user has — say so plainly and, if it warrants a human,
+    `request_handoff`. Don't fabricate, don't guess past a real gap.
+  - Be straight about uncertainty. Distinguish what you verified from what you assume.
+    If a result is partial, say which part is solid and which is open.
+  - Lead with the answer or the outcome, then the supporting detail. No filler, no
+    narrating tool calls for their own sake — just the substance and the result.
+soul_prompt: |
+  This assistant is a general-purpose autonomous agent. It pursues the user's goal
+  end to end, discovering and using whatever skills, tools, and subagents the task
+  needs, verifying its own work, and being honest about uncertainty and limits.
+fallback_messages:
+  - "I hit a snag on that step. Let me restate where things stand and what I'll try next."
+  - "Something went wrong on my end — give me the goal again and I'll pick the thread back up."

app/agents/default/attachment_policy.yaml

@@ -0,0 +1,8 @@
+enabled: true                  # master flag — false bypasses attachment parsing entirely
+max_image_bytes: 4000000       # raw-byte cap BEFORE base64 (~5.3MB data-uri); mirrors _cap_tool_text intent
+allowed_image_types: [".png", ".jpg", ".jpeg", ".gif", ".webp"]
+vision_unsupported_notice: >-
+  [note: this model can't read images; your attachment was ignored and only your
+  text was processed.]
+oversize_notice: "[image '{name}' skipped: {size} bytes exceeds cap of {cap} bytes]"
+unreadable_notice: "[image '{name}' skipped: {reason}]"

app/agents/default/compaction_policy.yaml

@@ -0,0 +1,24 @@
+enabled: true               # master flag — false fully bypasses compaction
+
+# Percentage-of-window triggering
+trigger_pct: 0.75           # compact when request exceeds 75% of usable input budget
+target_pct: 0.50            # compact down toward 50% (hysteresis band)
+reserved_output_tokens: null   # null → auto from model max_completion_tokens; int overrides (clamped to model cap)
+auto_output_ceiling: 8192      # ceiling applied when auto-deriving the output budget
+schema_headroom_pct: 0.05      # cushion for system prompt + bound tool schemas
+
+# Window resolution
+model_context_window: null     # null → resolve from OpenRouter /models; int → override
+default_context_window: 32000  # fallback when resolution fails
+absolute_trigger_cap: null     # optional cost cap: effective trigger = min(pct-budget, cap)
+
+# Retention / strategy
+keep_recent_min: 6
+max_tool_message_tokens: 4000  # fixed cap on a single ToolMessage at ingestion
+max_tool_message_pct: 0.15     # also cap it at 15% of usable input budget (per-model); effective cap = min of the two
+strategy: hybrid               # hybrid | trim
+
+# Summarizer
+summary_model: null            # null → reuse the agent's meta.yaml model
+summary_max_tokens: 512
+extract_facts: false           # Phase 4

app/agents/default/fs_policy.yaml

@@ -0,0 +1,30 @@
+# Default-agent filesystem-tools policy (read_file / grep / glob_files).
+# Core tools under namespace "fs" — always bound (see tool_policy.yaml core_tools).
+# Pure stdlib, cross-platform (Windows + POSIX), no shell-out. Set
+# `enabled: false` to disable — the tools are then never registered (invisible to
+# discovery and the permission view). A missing file falls back to these defaults.
+enabled: true
+
+# Confine every resolved path under the project root; refuse `..` escapes.
+# Keep ON unless the agent must read outside the repo.
+confine: true
+
+# read_file caps.
+max_read_bytes: 256000   # hard byte ceiling per read
+max_read_lines: 2000     # default line window when `limit` is omitted
+
+# Result caps (a truncation marker is appended when hit).
+max_grep_matches: 200
+max_glob_results: 200
+
+# Directories pruned by grep / never descended into.
+ignore_dirs:
+  - ".git"
+  - "node_modules"
+  - "__pycache__"
+  - ".venv"
+  - "venv"
+  - ".mypy_cache"
+  - ".pytest_cache"
+  - "dist"
+  - "build"

app/agents/default/guardrails_policy.yaml

@@ -0,0 +1,145 @@
+version: "1"
+enable_input_guard: true
+enable_output_guard: true
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Defense-in-depth guardrails for the Four-Blocks coaching agent.
+#
+# Input  (before the LLM):  prompt-injection (regex + ML)  +  harmful content.
+# Output (before the user): harmful content  +  PII leakage.
+#
+# IMPORTANT — this is a mental-health coaching app. It legitimately discusses
+# depression, guilt, anxiety and worthlessness. The Llama-Guard rules therefore
+# scope which categories block: self-harm (S11) and specialized-advice (S6) are
+# NOT blocked — those distress disclosures must reach the skill's crisis/wellbeing
+# flow, not get a cold refusal. Only genuinely malicious categories block.
+# ──────────────────────────────────────────────────────────────────────────────
+
+default_refusal_templates:
+  - "I'm unable to process that request right now."
+  - "That request can't be handled. Please try again."
+  - "Something went wrong evaluating your request. Please rephrase."
+
+backends:
+  regex_injection:
+    type: regex_injection
+    detect_typoglycemia: true
+    detect_base64: true
+    detect_hex: true
+    detect_char_spacing: true
+    min_encoded_len: 12
+
+  deberta:
+    type: local_classifier
+    model_name: protectai/deberta-v3-base-prompt-injection
+    device: cpu
+    batch_size: 8
+    injection_label: INJECTION
+    threshold: 0.5
+    fail_open: true
+
+  presidio:
+    type: presidio
+    languages:
+      - en
+    score_threshold: 0.5
+    entities:
+      - CREDIT_CARD
+      - CRYPTO
+      - EMAIL_ADDRESS
+      - IBAN_CODE
+      - IP_ADDRESS
+      - PHONE_NUMBER
+      - US_BANK_NUMBER
+      - US_DRIVER_LICENSE
+      - US_ITIN
+      - US_PASSPORT
+      - US_SSN
+    fail_open: false
+
+  llama_guard:
+    type: llama_guard
+    model_path: ./models/Llama-Guard-3-1B.Q4_K_M.gguf
+    n_ctx: 2048
+    n_threads: 4
+    max_tokens: 32
+    block_categories:
+      - S1   # Violent Crimes
+      - S2   # Non-Violent Crimes
+      - S3   # Sex Crimes
+      - S4   # Child Exploitation
+      - S9   # Indiscriminate Weapons
+      - S10  # Hate
+      - S14  # Code Interpreter Abuse / malware
+    fail_open: false
+
+input_rules:
+  - name: prompt_injection_regex
+    backend: regex_injection
+    enabled: true
+    severity: block
+    description: >
+      Deterministic detection of instruction-override, prompt-extraction,
+      role/tag spoofing, control-token injection, DAN jailbreaks, and encoded
+      or scrambled evasions of the same.
+    refusal_message: >
+      That request looks like an attempt to change how I work, so I can't act on it.
+      I can only follow my own guidelines — but if there's something on your mind, I'm here for that.
+    refusal_templates:
+      - "That looks like an attempt to change my instructions, so I can't act on it. If there's something you'd like to talk through, I'm here."
+      - "I can only follow my own guidelines, so I can't take that on. What's actually on your mind today?"
+
+  - name: prompt_injection_ml
+    backend: deberta
+    enabled: true
+    severity: block
+    description: >
+      ML classifier catching paraphrased or novel injection attempts that the
+      regex layer may miss.
+    refusal_message: >
+      That request looks like an attempt to change how I work, so I can't act on it.
+      I can only follow my own guidelines — but if there's something on your mind, I'm here for that.
+    refusal_templates:
+      - "That looks like an attempt to change my instructions, so I can't act on it. If there's something you'd like to talk through, I'm here."
+      - "I can only follow my own guidelines, so I can't take that on. What's actually on your mind today?"
+
+  - name: harmful_content
+    backend: llama_guard
+    enabled: false
+    severity: block
+    description: >
+      Block requests for instructions enabling violent/non-violent crime, sexual
+      crimes, child exploitation, weapons, hate, or malware. (Self-harm and
+      mental-health distress are intentionally NOT blocked here.)
+    refusal_message: >
+      I can't help with that. If something painful is going on for you, though, I'm glad to talk it through.
+    refusal_templates:
+      - "I can't help with that. If something painful is behind it, though, I'm here to talk."
+      - "That's not something I can help with. But if there's something you're struggling with, I'd like to hear it."
+
+output_rules:
+  - name: harmful_content_in_response
+    backend: llama_guard
+    enabled: false
+    severity: block
+    description: >
+      Block a response that contains harmful instructions (crime, weapons, hate,
+      malware, exploitation) even if the input looked benign.
+    refusal_message: >
+      I wasn't able to put together a response I'm comfortable sharing. Could you rephrase what you're after?
+    refusal_templates:
+      - "I wasn't able to give a response I'm comfortable sharing. Could you say more about what you need?"
+      - "That one didn't come out in a way I can share. Let's try it from a different angle."
+
+  - name: pii_leakage
+    backend: presidio
+    enabled: false
+    severity: block
+    description: >
+      Block a response that exposes personal identifiers — emails, phone numbers,
+      government IDs, or financial account numbers — that shouldn't be surfaced.
+    refusal_message: >
+      My response included some sensitive details I shouldn't share, so I've held it back. Could you ask again?
+    refusal_templates:
+      - "That response had sensitive details I shouldn't share, so I held it back. Could you ask again?"
+      - "I caught some private information in that reply and stopped it. Let's try again."

app/agents/default/handoff_policy.yaml

@@ -0,0 +1,12 @@
+# F07 Human Handoff policy.
+enabled: true                  # master flag — false → request_handoff unregistered
+operator_prompt: |
+  [HUMAN HANDOFF] The agent escalated this conversation.
+  Reason: {reason}
+  Type your reply to the user (blank = use fallback):
+timeout_seconds: null          # null → wait indefinitely (Dev CLI). Prod worker should bound it.
+on_timeout: fallback           # fallback | refuse | keep_waiting
+fallback_message: >
+  A team member will follow up with you shortly. In the meantime,
+  is there anything else I can help with?
+inject_as: assistant           # assistant | tool

app/agents/default/hooks.yaml

@@ -0,0 +1,36 @@
+# Hooks for the `default` (Generalist) agent.
+#
+# F10 shell audit: now that shell is enabled, every intent + outcome is logged
+# to data/audit/shell-audit.jsonl (dev) / the tool_audit table (prod). The model
+# calls the tool unqualified ("run_shell"), so the matcher globs the suffix to
+# also catch "shell:run_shell" / "shell_run_shell".
+version: "1"
+enabled: true
+hooks:
+  - name: shell-audit-intent
+    event: pre_tool
+    matcher: "*run_shell"
+    python: app.tools.shell_audit:log_intent
+    on_error: allow
+  - name: shell-audit-outcome
+    event: post_tool
+    matcher: "*run_shell"
+    python: app.tools.shell_audit:log_outcome
+    on_error: allow
+  # F27 loop guard: break a runaway streak of failing run_shell retries (deny +
+  # steer toward write_file). A genuinely different command is still allowed.
+  - name: shell-loop-guard
+    event: pre_tool
+    matcher: "*run_shell"
+    python: app.hooks.guards:shell_loop_guard
+    on_error: allow
+  # Verification loop guard (langfuse session test-104): deny + steer once the
+  # SAME failure signature (pytest/go test/jest/mypy/tsc/rustc/panic/traceback)
+  # recurs 2+ runs in a row, even across edits that made the shell commands
+  # look different (shell-loop-guard misses that case — it only compares
+  # command text, not the underlying failure).
+  - name: verification-loop-guard
+    event: pre_tool
+    matcher: "*run_shell"
+    python: app.hooks.guards:verification_loop_guard
+    on_error: allow