taguru 0.1.0__tar.gz

taguru-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+/target
+/data
+.DS_Store
+
+# SDK build/dev artifacts
+sdk/**/node_modules/
+sdk/**/dist/
+sdk/**/.venv/
+sdk/**/__pycache__/
+sdk/**/*.egg-info/
+sdk/**/.pytest_cache/
+sdk/**/.mypy_cache/
+sdk/**/.ruff_cache/
+
+# SDK example artifacts (the examples workspace deliberately commits no
+# lockfile: its SDK dependencies are file: paths into this repo)
+examples/langchain/**/node_modules/
+examples/langchain/package-lock.json
+examples/langchain/.venv/
+examples/langchain/**/__pycache__/

taguru-0.1.0/LICENSE

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

taguru-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: taguru
+Version: 0.1.0
+Summary: Python client SDK for the Taguru long-term semantic memory server
+Project-URL: Homepage, https://github.com/t0k0sh1/taguru
+Project-URL: Repository, https://github.com/t0k0sh1/taguru
+Author: Takashi Yamashina
+License-Expression: MIT
+License-File: LICENSE
+Keywords: knowledge-graph,llm,memory,rag,taguru
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: unasync>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# taguru (Python SDK)
+
+Official Python client SDK for the [Taguru](https://github.com/t0k0sh1/taguru)
+long-term semantic memory server. The TypeScript SDK (`taguru` on npm) exposes
+the identical surface — method names differ only by casing convention
+(`search_passages` ↔ `searchPassages`); data fields are the wire's own
+snake_case in both.
+
+```sh
+pip install taguru
+```
+
+```python
+from taguru import Taguru
+
+client = Taguru()  # defaults: $TAGURU_URL / $TAGURU_API_TOKEN, else http://127.0.0.1:8248
+client.contexts.create("sake", description="青嶺酒造という架空の酒蔵の知識")
+
+ctx = client.context("sake")
+ctx.add_associations([
+    {"subject": "青嶺酒造", "label": "代表銘柄", "object": "青嶺", "weight": 1.0, "source": "docs/aomine.md"},
+])
+ctx.store_passages({"docs/aomine.md": "青嶺酒造は1907年創業。代表銘柄は「青嶺」。"})
+
+result = ctx.retrieve("青嶺酒造")           # resolve → describe → activate → citations
+hits = ctx.search_passages("1907年に創業した")  # text lane (phrase as an answer)
+```
+
+`AsyncTaguru` is the same surface with `async`/`await`. The behavioral
+contract is the server's own protocol document — read it from the deployment
+you target: `client.protocol()` (`GET /protocol`).
+
+See the repository's `sdk/` directory for the full documentation, the
+LangChain integration (`langchain-taguru`), and the cross-language surface
+spec.

taguru-0.1.0/README.md

@@ -0,0 +1,35 @@
+# taguru (Python SDK)
+
+Official Python client SDK for the [Taguru](https://github.com/t0k0sh1/taguru)
+long-term semantic memory server. The TypeScript SDK (`taguru` on npm) exposes
+the identical surface — method names differ only by casing convention
+(`search_passages` ↔ `searchPassages`); data fields are the wire's own
+snake_case in both.
+
+```sh
+pip install taguru
+```
+
+```python
+from taguru import Taguru
+
+client = Taguru()  # defaults: $TAGURU_URL / $TAGURU_API_TOKEN, else http://127.0.0.1:8248
+client.contexts.create("sake", description="青嶺酒造という架空の酒蔵の知識")
+
+ctx = client.context("sake")
+ctx.add_associations([
+    {"subject": "青嶺酒造", "label": "代表銘柄", "object": "青嶺", "weight": 1.0, "source": "docs/aomine.md"},
+])
+ctx.store_passages({"docs/aomine.md": "青嶺酒造は1907年創業。代表銘柄は「青嶺」。"})
+
+result = ctx.retrieve("青嶺酒造")           # resolve → describe → activate → citations
+hits = ctx.search_passages("1907年に創業した")  # text lane (phrase as an answer)
+```
+
+`AsyncTaguru` is the same surface with `async`/`await`. The behavioral
+contract is the server's own protocol document — read it from the deployment
+you target: `client.protocol()` (`GET /protocol`).
+
+See the repository's `sdk/` directory for the full documentation, the
+LangChain integration (`langchain-taguru`), and the cross-language surface
+spec.

taguru-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "taguru"
+version = "0.1.0"
+description = "Python client SDK for the Taguru long-term semantic memory server"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Takashi Yamashina" }]
+keywords = ["taguru", "llm", "memory", "rag", "knowledge-graph"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1.0"]
+
+[project.urls]
+Homepage = "https://github.com/t0k0sh1/taguru"
+Repository = "https://github.com/t0k0sh1/taguru"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "unasync>=0.6",
+    "pyyaml>=6",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/taguru"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = [
+    # `object` is a wire-faithful parameter name on query(); shadowing the
+    # builtin there is a deliberate parity choice with the server vocabulary.
+    "A002",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Generated by scripts/generate_sync.py; import order and yield style are
+# artifacts of the unasync token replacement.
+"src/taguru/_sync/client.py" = ["I001", "UP028"]
+
+[tool.mypy]
+strict = true
+files = ["src"]

taguru-0.1.0/scripts/check_surface.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Check the Python SDK against sdk/spec/surface.yaml.
+
+Verifies, for both the sync and Async class variants: every declared method
+exists with exactly the declared positional (args) and keyword-only (options)
+parameter names, and no undeclared public method exists. Run with the `taguru`
+package importable (pip install -e sdk/python).
+"""
+
+from __future__ import annotations
+
+import inspect
+import sys
+from pathlib import Path
+
+import yaml
+
+import taguru
+
+SPEC_PATH = Path(__file__).resolve().parents[2] / "spec" / "surface.yaml"
+
+
+def params_of(func: object) -> tuple[list[str], list[str]]:
+    signature = inspect.signature(func)  # type: ignore[arg-type]
+    args: list[str] = []
+    options: list[str] = []
+    for name, param in signature.parameters.items():
+        if name == "self":
+            continue
+        if param.kind in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+        ):
+            args.append(name)
+        elif param.kind == inspect.Parameter.KEYWORD_ONLY:
+            options.append(name)
+    return args, options
+
+
+def main() -> int:
+    spec = yaml.safe_load(SPEC_PATH.read_text(encoding="utf-8"))
+    errors: list[str] = []
+
+    for func_name, declared in spec.get("functions", {}).items():
+        func = getattr(taguru, func_name, None)
+        if func is None:
+            errors.append(f"missing module function: taguru.{func_name}")
+            continue
+        args, _options = params_of(func)
+        if args != declared.get("args", []):
+            errors.append(f"taguru.{func_name}: args {args} != spec {declared.get('args', [])}")
+
+    for class_name, methods in spec.get("classes", {}).items():
+        for prefix in ("", "Async"):
+            variant = prefix + class_name
+            cls = getattr(taguru, variant, None)
+            if cls is None:
+                errors.append(f"missing class: taguru.{variant}")
+                continue
+            declared_names = set(methods)
+            actual_names = {
+                name
+                for name, member in vars(cls).items()
+                if not name.startswith("_") and callable(member)
+            }
+            for missing in sorted(declared_names - actual_names):
+                errors.append(f"{variant}.{missing}: declared in spec but not implemented")
+            for extra in sorted(actual_names - declared_names):
+                errors.append(f"{variant}.{extra}: public method not declared in spec")
+            for method_name, entry in methods.items():
+                if method_name not in actual_names:
+                    continue
+                entry = entry or {}
+                args, options = params_of(getattr(cls, method_name))
+                want_args = entry.get("args", [])
+                want_options = entry.get("options", [])
+                if args != want_args:
+                    errors.append(f"{variant}.{method_name}: args {args} != spec {want_args}")
+                if options != want_options:
+                    errors.append(
+                        f"{variant}.{method_name}: options {options} != spec {want_options}"
+                    )
+
+    if errors:
+        print(f"surface parity check FAILED ({len(errors)} problems):", file=sys.stderr)
+        for error in errors:
+            print(f"  - {error}", file=sys.stderr)
+        return 1
+    print("python surface matches sdk/spec/surface.yaml")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

taguru-0.1.0/scripts/generate_sync.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Generate taguru._sync.client from taguru._async.client via unasync.
+
+Run from anywhere; paths are resolved relative to this script. CI re-runs
+this and fails if the committed sync client is stale.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+import unasync
+
+ROOT = Path(__file__).resolve().parent.parent
+ASYNC_DIR = ROOT / "src" / "taguru" / "_async"
+SYNC_DIR = ROOT / "src" / "taguru" / "_sync"
+
+REPLACEMENTS = {
+    "AsyncTaguru": "Taguru",
+    "AsyncContexts": "Contexts",
+    "AsyncContext": "Context",
+    "AsyncClient": "Client",
+    "AsyncIterator": "Iterator",
+    "aiter_bytes": "iter_bytes",
+    "aread": "read",
+    "aclose": "close",
+    "asyncio": "time",
+    "__aenter__": "__enter__",
+    "__aexit__": "__exit__",
+}
+
+SYNC_DOCSTRING = '''"""Sync client — GENERATED, do not edit.
+
+This file is produced from ``taguru._async.client`` by
+``scripts/generate_sync.py`` (unasync). Edit the async source and regenerate.
+"""'''
+
+
+def main() -> int:
+    rule = unasync.Rule(
+        fromdir=str(ASYNC_DIR) + "/",
+        todir=str(SYNC_DIR) + "/",
+        additional_replacements=REPLACEMENTS,
+    )
+    unasync.unasync_files([str(ASYNC_DIR / "client.py")], [rule])
+
+    target = SYNC_DIR / "client.py"
+    text = target.read_text(encoding="utf-8")
+
+    # Replace the module docstring (unasync only rewrites NAME tokens).
+    text = re.sub(r'\A""".*?"""', SYNC_DOCSTRING, text, count=1, flags=re.DOTALL)
+
+    # The asyncio -> time replacement leaves `import time` twice.
+    lines = text.splitlines(keepends=True)
+    seen_import_time = False
+    kept: list[str] = []
+    for line in lines:
+        if line.strip() == "import time":
+            if seen_import_time:
+                continue
+            seen_import_time = True
+        kept.append(line)
+    target.write_text("".join(kept), encoding="utf-8")
+
+    # unasync keeps the async source's line wrapping, but dropping `async `
+    # lets some signatures fit on one line — and CI holds the committed file
+    # to `ruff format --check`. Format here so both checks agree.
+    subprocess.run([sys.executable, "-m", "ruff", "format", "--quiet", str(target)], check=True)
+
+    init = SYNC_DIR / "__init__.py"
+    if not init.exists():
+        init.write_text("", encoding="utf-8")
+    print(f"generated {target.relative_to(ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

taguru-0.1.0/src/taguru/__init__.py

@@ -0,0 +1,142 @@
+"""Python client SDK for the Taguru long-term semantic memory server.
+
+Quick start::
+
+    from taguru import Taguru
+
+    client = Taguru()  # TAGURU_URL / TAGURU_API_TOKEN, else localhost:8248
+    ctx = client.context("sake")
+    hits = ctx.search_passages("酒蔵の創業年", limit=5)
+
+``AsyncTaguru`` is the identical async surface. The behavioral contract is
+the server's own protocol document: ``client.protocol()`` (GET /protocol).
+"""
+
+from __future__ import annotations
+
+from ._async.client import AsyncContext, AsyncContexts, AsyncTaguru
+from ._errors import (
+    AuthenticationError,
+    ConflictError,
+    EmbeddingUnavailableError,
+    NotFoundError,
+    PayloadTooLargeError,
+    PermissionDeniedError,
+    RateLimitError,
+    RequestTimeoutError,
+    ServerError,
+    ServiceUnavailableError,
+    StorageFullError,
+    TaguruError,
+    TransportError,
+    UnexpectedStatusError,
+    ValidationError,
+)
+from ._models import (
+    Activation,
+    ActivationPage,
+    AliasEntry,
+    AliasPage,
+    Association,
+    Attribution,
+    BatchApplyResult,
+    Citation,
+    CompactOutcome,
+    ConceptDescription,
+    ContextMeta,
+    ContextPage,
+    ContextStats,
+    ContextUsage,
+    DirectoryEntry,
+    ExplorePage,
+    ImportOutcome,
+    LabelPage,
+    LabelUsage,
+    LaneEvidence,
+    MatchPage,
+    PassageHit,
+    PassageLanes,
+    PassageLookup,
+    Recollection,
+    RefreshBreakdown,
+    RefreshOutcome,
+    RetractOutcome,
+    RetrievalResult,
+    SourcePage,
+    StoredPassages,
+    TieredResolution,
+    TwinPair,
+    VocabularyAudit,
+)
+from ._shared import citation_key
+from ._sync.client import Context, Contexts, Taguru
+from ._types import AssocOp, QuestionSpec, SectionSpec
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # clients
+    "Taguru",
+    "AsyncTaguru",
+    "Context",
+    "AsyncContext",
+    "Contexts",
+    "AsyncContexts",
+    "citation_key",
+    # request types
+    "AssocOp",
+    "QuestionSpec",
+    "SectionSpec",
+    # errors
+    "TaguruError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "ValidationError",
+    "PayloadTooLargeError",
+    "RequestTimeoutError",
+    "RateLimitError",
+    "ServerError",
+    "ServiceUnavailableError",
+    "StorageFullError",
+    "EmbeddingUnavailableError",
+    "TransportError",
+    "UnexpectedStatusError",
+    # models
+    "Activation",
+    "ActivationPage",
+    "AliasEntry",
+    "AliasPage",
+    "Association",
+    "Attribution",
+    "BatchApplyResult",
+    "Citation",
+    "CompactOutcome",
+    "ConceptDescription",
+    "ContextMeta",
+    "ContextPage",
+    "ContextStats",
+    "ContextUsage",
+    "DirectoryEntry",
+    "ExplorePage",
+    "ImportOutcome",
+    "LabelPage",
+    "LabelUsage",
+    "LaneEvidence",
+    "MatchPage",
+    "PassageHit",
+    "PassageLanes",
+    "PassageLookup",
+    "Recollection",
+    "RefreshBreakdown",
+    "RefreshOutcome",
+    "RetractOutcome",
+    "RetrievalResult",
+    "SourcePage",
+    "StoredPassages",
+    "TieredResolution",
+    "TwinPair",
+    "VocabularyAudit",
+]