knowflow 0.1.0__py3-none-any.whl

knowflow/__init__.py

@@ -0,0 +1,4 @@
+# KnowFlow
+# Agent Knowledge Pipeline — Storage-agnostic, KB-agnostic, plug-and-play
+
+__version__ = "0.1.0"

knowflow/__main__.py

@@ -0,0 +1,3 @@
+"""knowflow.__main__ — Entry point for `python3 -m knowflow`"""
+from knowflow.cli import main
+main()

knowflow/adapters/knowledge/__init__.py

@@ -0,0 +1,42 @@
+"""knowflow/adapters/knowledge/__init__.py — Knowledge adapter registry"""
+from typing import Optional
+
+from knowflow.core.knowledge import KnowledgeAdapter, KnowledgePage
+
+_REGISTRY = {}
+
+def register(name: str, cls):
+    _REGISTRY[name.lower()] = cls
+
+def create_knowledge(name: str, config: Optional[dict] = None, **kwargs) -> KnowledgeAdapter:
+    """Factory: create a knowledge-base adapter by name.
+
+    两种调用方式都支持：
+        create_knowledge("obsidian", path="~/my-vault")        # 扁平参数
+        create_knowledge("obsidian", config={"path": "..."})   # 显式 config 字典
+    """
+    name = name.lower()
+    if name not in _REGISTRY:
+        available = list(_REGISTRY.keys())
+        raise ValueError(
+            f"Unknown knowledge base: '{name}'. Available: {available}"
+        )
+    if config is None:
+        config = dict(kwargs) if kwargs else None
+    elif kwargs:
+        config = {**config, **kwargs}
+    return _REGISTRY[name](config)
+
+
+# 别名：core/knowledge.py 的文档里写的是 create_kb，保持一致（曾导致 ImportError）
+create_kb = create_knowledge
+
+def list_backends() -> list[str]:
+    return sorted(_REGISTRY.keys())
+
+# Built-in adapters
+from . import local as _local
+register("local", _local.LocalKB)
+
+from . import obsidian as _obsidian
+register("obsidian", _obsidian.ObsidianKB)

knowflow/adapters/knowledge/local.py

@@ -0,0 +1,43 @@
+"""
+knowflow/adapters/knowledge/local.py — Local directory KB
+Simple markdown files in a directory.
+"""
+from pathlib import Path
+from knowflow.core.knowledge import KnowledgeAdapter, KnowledgePage, KnowledgeError
+
+
+class LocalKB(KnowledgeAdapter):
+    """Local markdown directory knowledge base"""
+    
+    def __init__(self, config: dict = None):
+        super().__init__(config)
+        path = config.get("path", "~/knowflow-output") if config else "~/knowflow-output"
+        self.root = Path(path).expanduser().resolve()
+        self.root.mkdir(parents=True, exist_ok=True)
+    
+    def name(self) -> str:
+        return f"Local ({self.root})"
+    
+    def sync(self, pages: list[KnowledgePage]) -> dict:
+        synced = 0
+        errors = []
+        for page in pages:
+            try:
+                target = self.root / page.path
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_text(page.content, encoding="utf-8")
+                synced += 1
+            except Exception as e:
+                errors.append(f"{page.path}: {e}")
+        return {"synced": synced, "skipped": 0, "errors": errors}
+    
+    def search(self, query: str, limit: int = 10) -> list[KnowledgePage]:
+        results = []
+        for md_file in sorted(self.root.rglob("*.md"))[:limit]:
+            if query.lower() in md_file.read_text(encoding="utf-8").lower():
+                results.append(KnowledgePage(
+                    title=md_file.stem,
+                    content=md_file.read_text(encoding="utf-8"),
+                    path=str(md_file.relative_to(self.root)),
+                ))
+        return results

knowflow/adapters/knowledge/obsidian.py

@@ -0,0 +1,64 @@
+"""
+knowflow/adapters/knowledge/obsidian.py — Obsidian vault KB
+Syncs markdown pages to an Obsidian-compatible vault directory.
+"""
+from pathlib import Path
+from knowflow.core.knowledge import KnowledgeAdapter, KnowledgePage, KnowledgeError
+
+
+class ObsidianKB(KnowledgeAdapter):
+    """Obsidian vault knowledge base"""
+    
+    def __init__(self, config: dict = None):
+        super().__init__(config)
+        path = config.get("path", "~/obsidian-vault") if config else "~/obsidian-vault"
+        self.root = Path(path).expanduser().resolve()
+        self.root.mkdir(parents=True, exist_ok=True)
+        self._ensure_vault()
+    
+    def _ensure_vault(self):
+        """Ensure .obsidian/ config exists for vault detection"""
+        obsidian_dir = self.root / ".obsidian"
+        obsidian_dir.mkdir(exist_ok=True)
+        app_file = obsidian_dir / "app.json"
+        if not app_file.exists():
+            import json
+            app_file.write_text(json.dumps({"promptDelete": False}, indent=2))
+    
+    def name(self) -> str:
+        return f"Obsidian ({self.root})"
+    
+    def sync(self, pages: list[KnowledgePage]) -> dict:
+        synced = 0
+        errors = []
+        for page in pages:
+            try:
+                target = self.root / page.path
+                target.parent.mkdir(parents=True, exist_ok=True)
+                # Add Obsidian frontmatter tags if provided
+                content = page.content
+                if page.tags:
+                    tags_line = "\n".join(f"  - {t}" for t in page.tags)
+                    frontmatter = f"---\ntags:\n{tags_line}\n---\n\n"
+                    if not content.startswith("---"):
+                        content = frontmatter + content
+                target.write_text(content, encoding="utf-8")
+                synced += 1
+            except Exception as e:
+                errors.append(f"{page.path}: {e}")
+        return {"synced": synced, "skipped": 0, "errors": errors}
+    
+    def search(self, query: str, limit: int = 10) -> list[KnowledgePage]:
+        results = []
+        for md_file in sorted(self.root.rglob("*.md"))[:limit]:
+            try:
+                content = md_file.read_text(encoding="utf-8")
+                if query.lower() in content.lower():
+                    results.append(KnowledgePage(
+                        title=md_file.stem,
+                        content=content,
+                        path=str(md_file.relative_to(self.root)),
+                    ))
+            except Exception:
+                continue
+        return results

knowflow/adapters/storage/__init__.py

@@ -0,0 +1,62 @@
+"""knowflow/adapters/storage/__init__.py — Storage adapter registry"""
+from typing import Optional
+
+from knowflow.core.storage import StorageAdapter
+
+
+# Registry: name → class
+_REGISTRY = {}
+
+
+def register(name: str, cls):
+    """Register a storage adapter"""
+    _REGISTRY[name.lower()] = cls
+
+
+def create_storage(name: str, config: Optional[dict] = None, **kwargs) -> StorageAdapter:
+    """Factory: create a storage adapter by name.
+
+    两种调用方式都支持：
+        create_storage("git", path="~/my-data")          # 扁平参数（文档里的写法）
+        create_storage("git", config={"path": "..."})    # 显式 config 字典
+    """
+    name = name.lower()
+    if name not in _REGISTRY:
+        available = list(_REGISTRY.keys())
+        raise ValueError(
+            f"Unknown storage backend: '{name}'. "
+            f"Available: {available}"
+        )
+    if config is None:
+        config = dict(kwargs) if kwargs else None
+    elif kwargs:
+        config = {**config, **kwargs}
+    return _REGISTRY[name](config)
+
+
+def list_backends() -> list[str]:
+    """List all registered storage backends"""
+    return sorted(_REGISTRY.keys())
+
+
+# ─── Import and register built-in adapters ─────────────────
+from . import local as _local_mod
+register("local", _local_mod.LocalStorage)
+
+from . import git as _git_mod
+register("git", _git_mod.GitStorage)
+
+# Optional adapters — import fails silently, available if deps installed
+try:
+    from . import s3 as _s3_mod
+    register("s3", _s3_mod.S3Storage)
+except ImportError:
+    pass
+
+# Quark 夸克网盘 — 依赖 kuake_cli，无额外Python包
+from . import quark as _quark_mod  # noqa
+register("quark", _quark_mod.QuarkStorage)
+
+# WebDAV — 依赖 requests，已预装
+from . import webdav as _webdav_mod  # noqa
+register("webdav", _webdav_mod.WebDAVStorage)

knowflow/adapters/storage/git.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+"""
+knowflow/adapters/storage/git.py — Git-backed storage
+======================================================
+Recommended backend: local files + full version history.
+
+Config:
+  path: str  (default: ~/knowflow-data)
+"""
+from pathlib import Path
+import subprocess
+import os
+import time
+import json
+from knowflow.core.storage import (
+    StorageAdapter, StorageItem, StorageError, StorageNotFoundError
+)
+
+
+class GitStorage(StorageAdapter):
+    """Git-backed storage with version history"""
+    
+    def __init__(self, config: dict = None):
+        super().__init__(config)
+        root = config.get("path", "~/knowflow-data") if config else "~/knowflow-data"
+        self.root = Path(root).expanduser().resolve()
+        self.root.mkdir(parents=True, exist_ok=True)
+        self._git("init", check=False)
+        self._ensure_user()
+    
+    def _resolve(self, path: str) -> Path:
+        clean = Path(path).as_posix().lstrip("/")
+        resolved = (self.root / clean).resolve()
+        if not str(resolved).startswith(str(self.root)):
+            raise StorageError(f"Path traversal blocked: {path}")
+        return resolved
+    
+    def _git(self, *args, check: bool = True) -> str:
+        try:
+            result = subprocess.run(
+                ["git", "-C", str(self.root), *args],
+                capture_output=True, text=True, timeout=30
+            )
+            if check and result.returncode != 0:
+                raise StorageError(f"Git: {result.stderr.strip() or 'unknown error'}")
+            return result.stdout.strip()
+        except subprocess.TimeoutExpired:
+            raise StorageError("Git command timed out")
+    
+    def _ensure_user(self):
+        if not self._git("config", "user.name", check=False):
+            self._git("config", "user.name", "KnowFlow")
+            self._git("config", "user.email", "knowflow@local")
+    
+    def read(self, path: str) -> str:
+        p = self._resolve(path)
+        if not p.exists():
+            raise StorageNotFoundError(f"Not found: {path}")
+        return p.read_text(encoding="utf-8")
+    
+    def read_binary(self, path: str) -> bytes:
+        p = self._resolve(path)
+        if not p.exists():
+            raise StorageNotFoundError(f"Not found: {path}")
+        return p.read_bytes()
+    
+    def write(self, path: str, content: str) -> str:
+        p = self._resolve(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content, encoding="utf-8")
+        return self._git("add", str(p.relative_to(self.root)))
+    
+    def write_binary(self, path: str, content: bytes) -> str:
+        p = self._resolve(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_bytes(content)
+        return self._git("add", str(p.relative_to(self.root)))
+    
+    def delete(self, path: str) -> bool:
+        p = self._resolve(path)
+        if not p.exists():
+            return False
+        if p.is_file():
+            p.unlink()
+        else:
+            # 与 LocalStorage 行为一致：目录递归删除
+            import shutil
+            shutil.rmtree(p)
+        self._git("add", "-A")
+        return True
+    
+    def exists(self, path: str) -> bool:
+        try:
+            return self._resolve(path).exists()
+        except StorageError:
+            return False
+    
+    def list(self, prefix: str = "") -> list[StorageItem]:
+        p = self._resolve(prefix) if prefix else self.root
+        if not p.exists():
+            return []
+        items = []
+        for child in sorted(p.iterdir()):
+            try:
+                stat = child.stat()
+                rel = child.relative_to(self.root).as_posix()
+                items.append(StorageItem(
+                    path=rel, size=stat.st_size if child.is_file() else 0,
+                    modified_at=stat.st_mtime, is_dir=child.is_dir(),
+                ))
+            except OSError:
+                continue
+        return items
+    
+    def walk(self, prefix: str = "") -> list[StorageItem]:
+        p = self._resolve(prefix) if prefix else self.root
+        if not p.exists():
+            return []
+        items = []
+        for root_dir, dirs, files in os.walk(str(p)):
+            root_path = Path(root_dir)
+            for name in files:
+                child = root_path / name
+                try:
+                    stat = child.stat()
+                    rel = child.relative_to(self.root).as_posix()
+                    items.append(StorageItem(path=rel, size=stat.st_size, modified_at=stat.st_mtime))
+                except OSError:
+                    continue
+        return sorted(items, key=lambda x: x.path)
+    
+    def commit(self, message: str = "") -> str:
+        self._git("add", "-A")
+        status = self._git("status", "--porcelain")
+        if not status:
+            return ""
+        if not message:
+            message = f"Auto-commit {time.strftime('%Y-%m-%d %H:%M:%S')}"
+        self._ensure_user()
+        self._git("commit", "-m", message)
+        return self._git("rev-parse", "HEAD")
+    
+    def log(self, max_count: int = 10) -> list[dict]:
+        fmt = '{"id":"%H","message":"%s","timestamp":"%aI","author":"%an"}'
+        output = self._git("log", f"--max-count={max_count}", f"--format={fmt}", check=False)
+        if not output:
+            return []
+        return [json.loads(line) for line in output.split("\n") if line.strip()]
+    
+    def diff(self, rev_a: str, rev_b: str, path: str = "") -> str:
+        args = ["diff", f"{rev_a}..{rev_b}"]
+        if path:
+            args.append("--", str(self._resolve(path)))
+        return self._git(*args, check=False)

knowflow/adapters/storage/local.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+"""
+knowflow/adapters/storage/local.py — Local filesystem storage
+===============================================================
+Simplest backend: plain directory on disk, no versioning.
+
+Config:
+  path: str  (default: ~/knowflow-data)
+"""
+from pathlib import Path
+import os
+import time
+from knowflow.core.storage import (
+    StorageAdapter, StorageItem, StorageError, StorageNotFoundError
+)
+
+
+class LocalStorage(StorageAdapter):
+    """Local filesystem storage backend"""
+    
+    def __init__(self, config: dict = None):
+        super().__init__(config)
+        root = config.get("path", "~/knowflow-data") if config else "~/knowflow-data"
+        self.root = Path(root).expanduser().resolve()
+        self.root.mkdir(parents=True, exist_ok=True)
+    
+    def _resolve(self, path: str) -> Path:
+        clean = Path(path).as_posix().lstrip("/")
+        resolved = (self.root / clean).resolve()
+        if not str(resolved).startswith(str(self.root)):
+            raise StorageError(f"Path traversal blocked: {path}")
+        return resolved
+    
+    def read(self, path: str) -> str:
+        p = self._resolve(path)
+        if not p.exists():
+            raise StorageNotFoundError(f"Not found: {path}")
+        return p.read_text(encoding="utf-8")
+    
+    def read_binary(self, path: str) -> bytes:
+        p = self._resolve(path)
+        if not p.exists():
+            raise StorageNotFoundError(f"Not found: {path}")
+        return p.read_bytes()
+    
+    def write(self, path: str, content: str) -> str:
+        p = self._resolve(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content, encoding="utf-8")
+        return ""
+    
+    def write_binary(self, path: str, content: bytes) -> str:
+        p = self._resolve(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_bytes(content)
+        return ""
+    
+    def delete(self, path: str) -> bool:
+        p = self._resolve(path)
+        if not p.exists():
+            return False
+        if p.is_file():
+            p.unlink()
+        else:
+            import shutil
+            shutil.rmtree(p)
+        return True
+    
+    def exists(self, path: str) -> bool:
+        try:
+            return self._resolve(path).exists()
+        except StorageError:
+            return False
+    
+    def list(self, prefix: str = "") -> list[StorageItem]:
+        p = self._resolve(prefix) if prefix else self.root
+        if not p.exists():
+            return []
+        items = []
+        for child in sorted(p.iterdir()):
+            try:
+                stat = child.stat()
+                rel = child.relative_to(self.root).as_posix()
+                items.append(StorageItem(
+                    path=rel,
+                    size=stat.st_size if child.is_file() else 0,
+                    modified_at=stat.st_mtime,
+                    is_dir=child.is_dir(),
+                ))
+            except OSError:
+                continue
+        return items
+    
+    def walk(self, prefix: str = "") -> list[StorageItem]:
+        p = self._resolve(prefix) if prefix else self.root
+        if not p.exists():
+            return []
+        items = []
+        for root_dir, dirs, files in os.walk(str(p)):
+            root_path = Path(root_dir)
+            for name in files:
+                child = root_path / name
+                try:
+                    stat = child.stat()
+                    rel = child.relative_to(self.root).as_posix()
+                    items.append(StorageItem(path=rel, size=stat.st_size, modified_at=stat.st_mtime))
+                except OSError:
+                    continue
+        return sorted(items, key=lambda x: x.path)