tina4-python 3.13.60__tar.gz → 3.13.62__tar.gz

{tina4_python-3.13.60 → tina4_python-3.13.62}/.gitignore

@@ -46,6 +46,10 @@ test_queue*.db
 /publish.sh
 /src/scss/
 /broken
+# Framework runtime artefacts under .tina4/ — the Context FTS5 index
+# (.tina4/context.db), agent.log, and file-write backups. Transient,
+# per-machine, never source-of-truth. Keep the whole dir out of git.
+/.tina4/
 # Framework runtime artefacts — BrokenTracker writes import-time and
 # route-time failure dumps here. They're transient (timestamped per
 # error) and contain stack traces, never source-of-truth content.

{tina4_python-3.13.60 → tina4_python-3.13.62}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina4-python
-Version: 3.13.60
+Version: 3.13.62
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT

{tina4_python-3.13.60 → tina4_python-3.13.62}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tina4-python"
-version = "3.13.60"
+version = "3.13.62"
 description = "Tina4 Python v3 — Zero-dependency, lightweight web framework"
 authors = [
     {name = "Andre van Zuydam", email = "andrevanzuydam@gmail.com"}

{tina4_python-3.13.60 → tina4_python-3.13.62}/tina4_python/CLAUDE.md

@@ -262,16 +262,16 @@ Queue(topic="tasks").push({"action": "send_email"})
 ### 11. Key tina4_python Gotchas
 
 1. **Database import**: Use `from tina4_python.database import Database` (NOT `from tina4_python import Database`)
-2. **noauth/secured import**: Use `from tina4_python.core.router import noauth, secured` (there is NO `tina4_python.Decorators` module). **Never** import `noauth` from `tina4_python.swagger` — that version only affects documentation, not actual auth.
+2. **noauth/secured import**: Use `from tina4_python.core.router import noauth, secured` (there is NO `tina4_python.Decorators` module). `tina4_python.swagger` does **not** export `noauth` (importing it raises `ImportError`). The real docs-only trap is **`@security()`** (from `tina4_python.swagger`): it sets OpenAPI metadata only and does NOT gate a route — use `@secured()`/`@noauth()` for actual auth.
 2b. **Decorator ordering**: Route decorators (`@get`, `@post`, etc.) must be the **innermost** (closest to the function). Swagger/meta decorators (`@description`, `@tags`, `@noauth`, `@secured`) go above. Correct: `@noauth()` → `@description(...)` → `@post(...)` → `def handler`. Wrong: `@post(...)` → `@description(...)` → `def handler` (will crash).
-3. **Jinja2 template syntax** (common mistakes):
+3. **Frond template syntax** (Frond is Jinja2-*like*, not Jinja2 — note the differences):
     - **Ternary operator supported**: Both `{{ x ? 'a' : 'b' }}` and `{{ 'a' if x else 'b' }}` work
-    - **elif not elseif**: Use `{% elif %}` NOT `{% elseif %}`
+    - **elif or elseif**: Frond accepts **both** `{% elif %}` and `{% elseif %}`
     - **Unescaped output**: Both `{{ var | safe }}` and `{{ var | raw }}` work for unescaped output
     - **format filter**: Use `{{ "%.2f" | format(value) }}` for number formatting
     - **e() filter has NO arguments**: Use `{{ var|e }}` NOT `{{ var|e('js') }}` — Jinja2's `|e` is HTML-only with no mode parameter (that's PHP Twig syntax)
     - **JS string escaping**: Use `{{ var|replace("'", "\\'") }}` to escape single quotes for inline JS onclick handlers
-    - **No `|escape('js')` or `|e('js')`**: These will throw `escape() takes 1 positional argument but 2 were given`
+    - **`|e`/`|escape` are HTML-only**: a mode arg like `|e('js')` is **ignored** by Frond (not an error) — for inline-JS escaping use `{{ var|replace("'", "\\'") }}`
     - **Ternary inline**: Use `{{ 's' if count != 1 else '' }}` NOT `{{ count != 1 ? 's' : '' }}`
     - **Default values**: Use `{{ var|default('fallback') }}` — works on undefined and None
     - **Chaining filters**: `{{ var|default('')|replace("'", "\\'") }}` — left to right
@@ -289,7 +289,7 @@ Queue(topic="tasks").push({"action": "send_email"})
 4. **fetch_one()**: Returns a plain dict (or None), NOT a DatabaseResult
 5. **Dict access**: All query results use dict access `row["column"]` not attribute access `row.column`
 6. **Connection strings**: v3 uses standard URL format: `driver://host:port/database` with separate `username` and `password` parameters. Example: `Database("firebird://localhost:3050//path/to/db", "SYSDBA", "masterkey")`. Environment variable: `TINA4_DATABASE_URL`.
-7. **Running the app**: `uv run python app.py <port> <name>` — port and name are CLI args handled by tina4_python
+7. **Running the app**: use the `tina4` CLI — `tina4 serve`. The framework **refuses to boot via a plain `python app.py`** (it must be launched by the CLI; `TINA4_OVERRIDE_CLIENT=true` only for embedding). Port/name are CLI args.
 8. **SCSS**: Files in `src/scss/` are auto-compiled to `src/public/css/` on startup
 12. **Background tasks**: Use `background(fn, interval)` from `tina4_python.core.server` — never use `threading.Thread` for periodic work. The `background()` function runs tasks cooperatively in the asyncio event loop with proper shutdown handling.
 

{tina4_python-3.13.60 → tina4_python-3.13.62}/tina4_python/__init__.py

@@ -8,7 +8,7 @@ Tina4 Python v3.0 — Zero-dependency, lightweight web framework.
 
 One import, everything works.
 """
-__version__ = "3.13.60"
+__version__ = "3.13.62"
 
 # ── Route decorators ──
 from tina4_python.core.router import (  # noqa: E402, F401

tina4_python-3.13.62/tina4_python/context/__init__.py

@@ -0,0 +1,371 @@
+# Tina4Python
+#
+# Context — a native, zero-dependency code/doc grounding index.
+#
+# Lets a Tina4 app ground its own AI assistant on its own source, offline:
+# it walks the project, chunks code on def/class boundaries and docs as prose,
+# and answers keyword/fuzzy queries over a SQLite FTS5 index (Python stdlib
+# ``sqlite3`` — FTS5 + ``bm25()`` are built in, so NO new dependency).
+#
+# The retrieval core is a thin port of the proven slice of neemee
+# (longmem-harness: memory_systems.SqliteFTS + pipeline.retrieve's stable
+# source-over-tests / definition-first reorderings). It COMPLEMENTS the
+# ``api_*`` reflection tools: ``api_*`` is exact structural lookup, Context is
+# fuzzy/semantic FTS over source + docs.
+#
+#   from tina4_python.context import Context
+#   ctx = Context(".tina4/context.db")
+#   ctx.index_root("src")
+#   ctx.search("where is the auth token issued?", k=5)
+#   #  -> [{"path": "src/auth.py", "score": 2.31, "snippet": "..."}, ...]
+#
+# On-disk index defaults to ``.tina4/context.db`` (gitignored). Guards a
+# sqlite build without FTS5: if absent, the Context degrades to safe no-ops
+# rather than crashing the app.
+
+import os
+import re
+import sqlite3
+import threading
+from pathlib import Path
+
+from .chunker import (
+    chunk_code,
+    chunk_text,
+    fold,
+    light_stem,
+    terms,
+)
+
+__all__ = ["Context", "default_context", "existing_context"]
+
+# File classification — mirrors neemee's repo walk.
+CODE_EXTS = {".py", ".php", ".js", ".mjs", ".ts", ".rb",
+             ".pas", ".dpr", ".dpk", ".inc", ".dfm", ".fmx"}
+DOC_EXTS = {".md", ".txt", ".rst", ".twig", ".html"}
+# deploy/CLI/env answers live in config files, not sources — chunk as code
+# (line windows), since sentence chunking shreds YAML/Dockerfiles.
+CONFIG_EXTS = {".toml", ".yml", ".yaml"}
+SPECIAL_FILES = {"dockerfile", "makefile", "docker-compose.yml",
+                 "package.json", "composer.json",
+                 ".env.example", ".env.sample"}
+# Same dirs neemee skips, plus Tina4 runtime dirs that hold no source of truth
+# (our own index/backups, session blobs, logs).
+SKIP_DIRS = {".git", "__pycache__", "node_modules", "vendor", "dist",
+             "build", "coverage", ".idea", ".venv", "venv", ".pytest_cache",
+             ".tina4", "sessions", "logs"}
+
+# generic question/code vocabulary that never NAMES a symbol — kept small.
+_DEF_STOP = frozenset(
+    "the and what how does can which where when who why list all available "
+    "module class function functions method methods def get set new return "
+    "import from with that this are is was for into use used".split())
+
+# a chunk that DEFINES a queried symbol ('def get_token', 'class Widget')
+# should out-rank one that merely USES it. Matched against the folded body.
+_DEF_KW = r"(?:async def|def|class|function|fn|func|interface|trait)"
+
+
+def _fts5_supported() -> bool:
+    """True if this interpreter's sqlite3 was built with FTS5."""
+    try:
+        conn = sqlite3.connect(":memory:")
+        try:
+            conn.execute("CREATE VIRTUAL TABLE _probe USING fts5(x)")
+            return True
+        finally:
+            conn.close()
+    except sqlite3.OperationalError:
+        return False
+    except Exception:
+        return False
+
+
+class Context:
+    """A SQLite FTS5 index over a project's source + docs.
+
+    Methods:
+        index_path(file, label=None) -> int   upsert one file (delete-by-path,
+                                               re-chunk, insert); reindex-safe.
+        index_root(root)             -> int   walk a tree, index every eligible
+                                               file (skips vendor/build dirs).
+        search(query, k=5)           -> list  [{path, score, snippet}] ranked by
+                                               bm25() with source-over-tests +
+                                               definition-first reordering.
+    """
+
+    def __init__(self, path="./.tina4/context.db", fts5_check=None):
+        """``path`` is the on-disk index file (its parent dir is created).
+        ``fts5_check`` overrides FTS5 detection (used by tests to exercise the
+        graceful-degradation path); defaults to a real probe of this build.
+        """
+        self.path = str(path)
+        self._lock = threading.Lock()
+        self.conn = None
+        self.root = None            # set by index_root; reindex_file relabels against it
+        check = fts5_check or _fts5_supported
+        self.available = bool(check())
+        if not self.available:
+            return
+        parent = Path(self.path).parent
+        if str(parent) not in ("", "."):
+            parent.mkdir(parents=True, exist_ok=True)
+        # One connection shared across threads (the dev-MCP handler may run on
+        # a worker thread) with a lock serializing access — a same-thread-only
+        # connection would reject those calls outright.
+        self.conn = sqlite3.connect(self.path, check_same_thread=False)
+        self._ensure_table()
+
+    # ── FTS5 availability ───────────────────────────────────────
+    @classmethod
+    def fts5_available(cls) -> bool:
+        """Whether this Python's sqlite3 supports FTS5 (module-level probe)."""
+        return _fts5_supported()
+
+    # ── schema ──────────────────────────────────────────────────
+    def _ensure_table(self):
+        # `body` holds fold(text) so query/index tokenization is symmetric;
+        # `raw` (UNINDEXED) keeps the original text to return as a snippet;
+        # `path`/`cid` (UNINDEXED) are metadata used for upsert + citation.
+        self.conn.execute(
+            "CREATE VIRTUAL TABLE IF NOT EXISTS chunks "
+            "USING fts5(cid UNINDEXED, path UNINDEXED, raw UNINDEXED, body)"
+        )
+        self.conn.commit()
+
+    def reset(self):
+        """Drop and recreate the index (full rebuild starting point)."""
+        if not self.available:
+            return
+        with self._lock:
+            self.conn.execute("DROP TABLE IF EXISTS chunks")
+            self._ensure_table()
+
+    # ── indexing ────────────────────────────────────────────────
+    @staticmethod
+    def _chunks_for(label, text):
+        """(index, chunk_text) pairs — code files on def/class boundaries,
+        everything else (docs) as prose."""
+        ext = os.path.splitext(label)[1].lower()
+        special = os.path.basename(label).lower() in SPECIAL_FILES
+        if ext in CODE_EXTS or ext in CONFIG_EXTS or special:
+            return chunk_code(text, path=label)
+        return chunk_text(text)
+
+    def index_path(self, file, label=None) -> int:
+        """UPSERT one file into the index: delete this path's existing chunks,
+        re-chunk the current contents, insert. A single file save re-indexes
+        just that file (sub-100ms). ``label`` is the stored/citation path
+        (defaults to ``str(file)``) and MUST be stable across calls for the
+        same file so the delete targets the right rows. Returns rows inserted.
+        """
+        if not self.available:
+            return 0
+        stored = str(label) if label is not None else str(file)
+        try:
+            text = Path(file).read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            return 0
+        rows = [
+            (f"{stored}:{i}", stored, chunk, fold(chunk))
+            for i, chunk in self._chunks_for(stored, text)
+        ]
+        with self._lock:
+            self.conn.execute("DELETE FROM chunks WHERE path = ?", (stored,))
+            if rows:
+                self.conn.executemany(
+                    "INSERT INTO chunks(cid, path, raw, body) VALUES (?, ?, ?, ?)",
+                    rows,
+                )
+            self.conn.commit()
+        return len(rows)
+
+    @staticmethod
+    def _eligible(filename) -> bool:
+        """True if a file should be indexed (the per-file filter used by both
+        index_root and reindex_file). Directory skipping is handled separately."""
+        fn = filename.lower()
+        if fn.endswith(".min.js"):
+            return False
+        ext = os.path.splitext(fn)[1]
+        return (ext in CODE_EXTS or ext in DOC_EXTS or ext in CONFIG_EXTS
+                or fn in SPECIAL_FILES)
+
+    def index_root(self, root) -> int:
+        """Walk ``root``, indexing every eligible file (skips vendor/build/
+        runtime dirs). Paths are stored RELATIVE to ``root`` for clean
+        citations. Records ``root`` so reindex_file can relabel a changed file
+        consistently. Returns the total number of chunks inserted."""
+        if not self.available:
+            return 0
+        root = Path(root).resolve()
+        self.root = root
+        total = 0
+        for dirpath, dirnames, filenames in os.walk(root):
+            # prune skip-dirs and dotdirs in place
+            dirnames[:] = [d for d in dirnames
+                           if d not in SKIP_DIRS and not d.startswith(".")]
+            for fn in sorted(filenames):
+                if not self._eligible(fn):
+                    continue
+                full = Path(dirpath) / fn
+                rel = str(full.relative_to(root))
+                total += self.index_path(full, label=rel)
+        return total
+
+    def reindex_file(self, changed_path) -> int:
+        """Re-index a single changed file into the LIVE index — the hook the dev
+        WebSocket reload trigger (POST /__dev/api/reload) calls so code_search
+        tracks edits without a rebuild. Resolves ``changed_path`` against the
+        indexed root, then: outside root / under a skip-or-dot dir / ineligible
+        → skip (-1); deleted → drop its chunks (0); otherwise UPSERT (rows).
+        No-op (-1) until index_root has run (nothing to keep fresh yet)."""
+        if not self.available or self.root is None:
+            return -1
+        p = Path(changed_path)
+        if not p.is_absolute():
+            # the reload trigger reports paths relative to the project root (cwd
+            # during `tina4 serve`); the index root may be a subdir like src/.
+            p = Path.cwd() / changed_path
+        try:
+            rel = p.resolve().relative_to(self.root)
+        except (ValueError, OSError):
+            return -1                          # outside the indexed root
+        if set(rel.parts) & SKIP_DIRS or any(part.startswith(".") for part in rel.parts[:-1]):
+            return -1                          # under a skipped / dot dir
+        if not self._eligible(rel.name):
+            return -1
+        stored = str(rel)
+        if not p.exists():                     # deleted → drop its chunks
+            with self._lock:
+                self.conn.execute("DELETE FROM chunks WHERE path = ?", (stored,))
+                self.conn.commit()
+            return 0
+        return self.index_path(p, label=stored)
+
+    # ── query ───────────────────────────────────────────────────
+    def _match_expr(self, query):
+        """Build the FTS5 MATCH string: each folded query token (plus its
+        light stem) as a quoted OR term. Quoting keeps it injection-safe."""
+        toks = set()
+        for t in terms(query):
+            toks.add(t)
+            toks.add(light_stem(t))
+        toks.discard("")
+        if not toks:
+            return None, set()
+        expr = " OR ".join('"%s"' % t for t in sorted(toks))
+        return expr, toks
+
+    @staticmethod
+    def _is_testlike(path):
+        s = (path or "").lower()
+        return any(p in s for p in ("/test", "test/", "test_", "_test.",
+                                    ".test.", "/example", "example/"))
+
+    def _defines(self, folded_body, symbols):
+        if not symbols:
+            return False
+        pat = re.compile(
+            _DEF_KW + r"\s+(?:" + "|".join(re.escape(s) for s in symbols)
+            + r")(?![a-z0-9])")
+        return bool(pat.search(folded_body))
+
+    def search(self, query, k=5):
+        """Return the top-``k`` chunks as ``[{path, score, snippet}]``, ranked
+        by ``bm25()`` then reordered with two stable, proven passes:
+          - source-over-tests: a test that merely mentions a symbol sinks below
+            the source that defines it (skipped when the query is about tests);
+          - definition-first: a chunk that DEFINES a queried symbol rises above
+            chunks that only use it.
+        Score is a higher-is-better float (sqlite's bm25 sign flipped).
+        """
+        if not self.available:
+            return []
+        expr, _ = self._match_expr(query)
+        if expr is None:
+            return []
+        pool_n = max(k * 3, 15)
+        with self._lock:
+            rows = self.conn.execute(
+                "SELECT path, raw, body, bm25(chunks) AS s FROM chunks "
+                "WHERE chunks MATCH ? ORDER BY s LIMIT ?",
+                (expr, pool_n),
+            ).fetchall()
+        if not rows:
+            return []
+
+        # candidate symbol names from the query (drop generic vocab).
+        symbols = {t for t in terms(query) if len(t) >= 3 and t not in _DEF_STOP}
+        about_tests = "test" in query.lower()
+
+        def sort_key(item):
+            idx, (path, raw, body, s) = item
+            is_test = 1 if (not about_tests and self._is_testlike(path)) else 0
+            is_def = 0 if self._defines(body, symbols) else 1
+            return (is_test, is_def, idx)   # bm25 order (idx) breaks ties
+
+        ordered = sorted(enumerate(rows), key=sort_key)
+        out = []
+        for _, (path, raw, body, s) in ordered[:k]:
+            out.append({
+                "path": path,
+                "score": round(-float(s), 6),   # bm25: more negative = better
+                "snippet": self._snippet(raw),
+            })
+        return out
+
+    @staticmethod
+    def _snippet(raw, limit=280):
+        text = (raw or "").strip()
+        if len(text) <= limit:
+            return text
+        return text[:limit].rstrip() + " ..."
+
+    # ── misc ────────────────────────────────────────────────────
+    def count(self) -> int:
+        if not self.available:
+            return 0
+        with self._lock:
+            return self.conn.execute("SELECT count(*) FROM chunks").fetchone()[0]
+
+    def is_empty(self) -> bool:
+        return self.count() == 0
+
+    def close(self):
+        if self.conn is not None:
+            with self._lock:
+                self.conn.close()
+                self.conn = None
+
+
+# ── process-wide shared index ───────────────────────────────────
+# code_search (dev MCP) and the dev-reload reindex hook must share ONE index so
+# a saved file is immediately searchable. Keyed by resolved db path.
+_shared_contexts: dict = {}
+
+
+def _db_key(db=None) -> str:
+    return str((Path(db) if db else Path.cwd() / ".tina4" / "context.db").resolve())
+
+
+def default_context(root=None, db=None) -> "Context":
+    """Get (or create) the process-wide Context at ``db`` (default
+    ``<cwd>/.tina4/context.db``). If ``root`` is given and the index is empty,
+    builds it once. This is what code_search uses so the reload hook can keep
+    the SAME index fresh."""
+    key = _db_key(db)
+    ctx = _shared_contexts.get(key)
+    if ctx is None:
+        ctx = Context(key)
+        _shared_contexts[key] = ctx
+    if root is not None and ctx.available and ctx.is_empty():
+        ctx.index_root(root)
+    return ctx
+
+
+def existing_context(db=None):
+    """Return the already-created shared Context for ``db`` (or None). Used by
+    the reload hook so a file change reindexes an EXISTING index but never
+    creates one on its own (nothing to keep fresh until code_search runs)."""
+    return _shared_contexts.get(_db_key(db))

tina4_python-3.13.62/tina4_python/context/chunker.py

@@ -0,0 +1,120 @@
+# Tina4Python
+#
+# Text folding + chunking for the Context subsystem.
+#
+# A thin, idiomatic port of the proven slice of neemee's tokenizer/chunkers
+# (longmem-harness: pipeline.chunk_code / chunk_text, memory_systems.fold).
+# Pure stdlib — ``re``/``unicodedata`` only. Nothing here touches SQLite; it
+# produces the (folded body, raw text) pairs the FTS5 index stores.
+
+import re
+import unicodedata
+
+# join comma-grouped numbers ("24,601" -> "24601") and split camelCase
+# ("ForeignKeyField" -> "foreign key field") so a query token reaches a
+# code identifier. snake_case already splits for free at the tokenizer.
+_NUM_COMMA = re.compile(r"(?<=\d),(?=\d)")
+_CAMEL = re.compile(r"(?<=[a-z0-9])(?=[A-Z])")
+_WORD_RE = re.compile(r"[a-z0-9]+")
+
+# Sentence boundary = end punctuation FOLLOWED BY whitespace/EOL, or a newline.
+# NOT a bare '.', which would shred embedded code in prose ("db.fetch()" ->
+# "db. fetch()"). Intra-token dots (method calls, module paths) stay intact.
+_SENT = re.compile(r"(?<=[.!?])\s+|\n+")
+
+# Chunk boundaries across languages: python defs/classes/decorators, php/js
+# functions and methods, ts exports/interfaces, php traits, and Object Pascal
+# unit/type/routine headers (Delphi is case-insensitive, accept either case).
+_TOPLEVEL = re.compile(
+    r"^(async def |def |class |@\w"
+    r"|\s*(?:public |private |protected |static |final |abstract )*function \w"
+    r"|(?:export )?(?:default )?(?:abstract )?class "
+    r"|interface |trait "
+    r"|export (?:const|function|interface|type|async) "
+    r"|[Uu]nit |[Pp]rocedure |[Ff]unction |[Cc]onstructor |[Dd]estructor "
+    r"|[Tt]ype$)"
+)
+
+
+def fold(text: str) -> str:
+    """Lowercase, strip diacritics, join comma-grouped numbers, split camelCase.
+
+    Applied symmetrically to the indexed ``body`` and to query tokens so
+    matching is consistent: a query for ``field`` reaches ``IntegerField``.
+    """
+    text = _CAMEL.sub(" ", _NUM_COMMA.sub("", text)).lower()
+    return unicodedata.normalize("NFKD", text) \
+        .encode("ascii", "ignore").decode("ascii")
+
+
+def light_stem(token: str) -> str:
+    """Fold simple plurals: strip one trailing 's', never from ss/us/is
+    endings (class, status, axis). QUERY-side only — so ``fields`` in a
+    question also reaches ``Field`` definitions."""
+    if len(token) > 3 and token.endswith("s") and not token.endswith(("ss", "us", "is")):
+        return token[:-1]
+    return token
+
+
+def terms(text: str):
+    """Accent-folded lowercase alphanumeric tokens (digits kept)."""
+    return _WORD_RE.findall(fold(text))
+
+
+def _pack(segments, max_lines):
+    """Pack line-segments into chunks of at most ``max_lines`` lines,
+    hard-splitting any single oversized segment."""
+    chunks, cur = [], []
+    for seg in segments:
+        while len(seg) > max_lines:            # oversized segment: hard split
+            if cur:
+                chunks.append(cur)
+                cur = []
+            chunks.append(seg[:max_lines])
+            seg = seg[max_lines:]
+        if cur and len(cur) + len(seg) > max_lines:
+            chunks.append(cur)
+            cur = []
+        cur += seg
+    if cur:
+        chunks.append(cur)
+    return chunks
+
+
+def chunk_code(text: str, path: str = "", max_lines: int = 60):
+    """Chunk source on top-level def/class/decorator boundaries (sentence
+    chunking shreds code). Segments are packed up to ``max_lines``, and every
+    chunk starts with a ``# file: <path>`` line so the path's tokens are
+    indexed — 'where is the router?' should match core/router.py by name.
+
+    Returns a list of ``(index, chunk_text)`` pairs.
+    """
+    lines = text.splitlines()
+    bounds = [i for i, ln in enumerate(lines) if _TOPLEVEL.match(ln)]
+    if not bounds or bounds[0] != 0:
+        bounds = [0] + bounds
+    segments = [lines[a:b] for a, b in zip(bounds, bounds[1:] + [len(lines)])]
+
+    header = f"# file: {path}" if path else None
+    out = []
+    for i, ch in enumerate(_pack(segments, max_lines)):
+        body = "\n".join(([header] if header else []) + ch)
+        out.append((i, body))
+    return out
+
+
+def chunk_text(text: str, max_words: int = 350):
+    """Chunk prose/docs into sentence-packed windows of at most ``max_words``
+    words. Returns a list of ``(index, chunk_text)`` pairs."""
+    sents = [s.strip() for s in _SENT.split(text) if s.strip()]
+    chunks, cur, cur_words = [], [], 0
+    for s in sents:
+        w = len(s.split())
+        if cur and cur_words + w > max_words:
+            chunks.append(" ".join(cur))
+            cur, cur_words = [], 0
+        cur.append(s)
+        cur_words += w
+    if cur:
+        chunks.append(" ".join(cur))
+    return list(enumerate(chunks))

{tina4_python-3.13.60 → tina4_python-3.13.62}/tina4_python/dev_admin/__init__.py

@@ -2000,6 +2000,19 @@ async def _api_reload(request, response):
     except Exception as e:
         Log.error(f"Re-discover on reload failed: {e}")
 
+    # Keep the code Context index LIVE on the same WebSocket-reload trigger:
+    # reindex just the changed file (UPSERT) so the dev-MCP code_search reflects
+    # the edit immediately. Only touches an already-built index (existing_context
+    # never creates one); guarded so a context failure never breaks the reload.
+    try:
+        if _reload_file[0]:
+            from tina4_python.context import existing_context
+            _ctx = existing_context()
+            if _ctx is not None:
+                _ctx.reindex_file(_reload_file[0])
+    except Exception as e:
+        Log.error(f"Context reindex on reload failed: {e}")
+
     # WebSocket-primary reload: push an instant message to every browser
     # connected on /__dev_reload. The toolbar client (and the dev-admin
     # dashboard) act on this immediately — the mtime poll above is only a

{tina4_python-3.13.60 → tina4_python-3.13.62}/tina4_python/mcp/tools.py

@@ -971,6 +971,36 @@ def register_dev_tools(server):
         spec = Docs(project_root=str(project_root)).method_spec(class_, name)
         return spec if spec is not None else {"error": f"method not found: {class_}.{name}"}
 
+    # ── Code/doc grounding (tina4_python.context) ───────────────
+    # Sibling of api_* but the DUAL of it: api_* is exact structural
+    # reflection (class/method signatures); code_search is fuzzy/semantic
+    # FTS over the project's own SOURCE + docs. Use code_search for
+    # "where/how is X done in THIS codebase?" and api_* for "what's the
+    # signature of X?". Backed by a zero-dependency SQLite FTS5 index at
+    # .tina4/context.db, kept in a closure so repeat calls reuse it.
+    # Held as a PROCESS-WIDE shared Context (context.default_context) so the dev
+    # WebSocket reload hook can keep the SAME index fresh on every file save.
+    def _code_root():
+        return project_root / "src" if (project_root / "src").is_dir() else project_root
+
+    def code_search(query: str, k: int = 5, rebuild: bool = False) -> list:
+        """Fuzzy/semantic search over THIS project's own source + docs
+        (SQLite FTS5, zero-dep). Ranks definitions above tests that merely
+        mention a symbol. Use for 'where is X done here?'; use api_* for exact
+        signatures. First call (or rebuild=True) indexes src/ (falls back to
+        the project root); thereafter the dev-reload hook keeps it live on save.
+        Returns [{path, score, snippet}]."""
+        from tina4_python.context import default_context
+        ctx = default_context(root=_code_root(),
+                              db=str(project_root / ".tina4" / "context.db"))
+        if not ctx.available:
+            return {"error": "SQLite FTS5 is not available in this Python build; "
+                             "code_search is disabled."}
+        if rebuild:
+            ctx.reset()
+            ctx.index_root(_code_root())
+        return ctx.search(query, k=k)
+
     # ── Register all tools ──────────────────────────────────────
 
     tools = [
@@ -1029,6 +1059,12 @@ def register_dev_tools(server):
         ("api_search", api_search, "Live API search — finds framework + user classes/methods by name/summary. Use BEFORE guessing a method exists."),
         ("api_class", api_class, "Live class reflection — returns full method list + signatures for an FQN."),
         ("api_method", api_method, "Live method reflection — returns signature, params, return type, file, line."),
+
+        # ── Code/doc grounding (semantic FTS over this repo's source) ──
+        # code_search is the fuzzy DUAL of the structural api_* tools:
+        # api_* = exact signature lookup; code_search = "where/how is X
+        # done in THIS codebase?" over source + docs (zero-dep FTS5).
+        ("code_search", code_search, "Fuzzy/semantic search over THIS project's source + docs (FTS5). Use for 'where/how is X done here?'; api_* for exact signatures."),
     ]
 
     for name, handler, description in tools: