openviking 0.1.10__tar.gz → 0.1.11__tar.gz

{openviking-0.1.10/openviking.egg-info → openviking-0.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openviking
-Version: 0.1.10
+Version: 0.1.11
 Summary: An Agent-native context database
 Author-email: ByteDance <noreply@bytedance.com>
 License: Apache-2.0

{openviking-0.1.10 → openviking-0.1.11}/docs/en/concepts/07-extraction.md

@@ -26,7 +26,7 @@ Parser handles document format conversion and structuring, creating file structu
 | Plain text | TextParser | .txt | Supported |
 | PDF | PDFParser | .pdf | Supported |
 | HTML | HTMLParser | .html, .htm | Supported |
-| Code | CodeParser | .py, .js, .go, etc. |  |
+| Code | CodeRepositoryParser | .py, .js, .go, etc. |  |
 | Image | ImageParser | .png, .jpg, etc. |  |
 | Video | VideoParser | .mp4, .avi, etc. |  |
 | Audio | AudioParser | .mp3, .wav, etc. |  |

{openviking-0.1.10 → openviking-0.1.11}/docs/zh/concepts/07-extraction.md

@@ -25,7 +25,7 @@ Parser 负责文档格式转换和结构化，在临时目录创建文件结构
 | 纯文本 | TextParser | .txt | 已支持 |
 | PDF | PDFParser | .pdf | 已支持 |
 | HTML | HTMLParser | .html, .htm | 已支持 |
-| 代码 | CodeParser | .py, .js, .go 等 |  |
+| 代码 | CodeRepositoryParser | github 代码仓库等 | 已支持 |
 | 图片 | ImageParser | .png, .jpg 等 |  |
 | 视频 | AudioParser | .mp3, .wav 等 |  |
 | 音频 | VideoParser | .mp4, .avi 等 |  |

{openviking-0.1.10 → openviking-0.1.11}/openviking/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.1.10'
-__version_tuple__ = version_tuple = (0, 1, 10)
+__version__ = version = '0.1.11'
+__version_tuple__ = version_tuple = (0, 1, 11)
 
-__commit_id__ = commit_id = 'ga11f118d6'
+__commit_id__ = commit_id = 'ga9b59cce8'

{openviking-0.1.10 → openviking-0.1.11}/openviking/async_client.py

@@ -205,7 +205,7 @@ class AsyncOpenViking:
         timeout: float = None,
     ) -> Dict[str, Any]:
         """Add resource to OpenViking (only supports resources scope).
-
+        like: viking://resources/github/volcengine/OpenViking
         Args:
             wait: Whether to wait for semantic extraction and vectorization to complete
             timeout: Wait timeout in seconds

{openviking-0.1.10 → openviking-0.1.11}/openviking/core/context.py

@@ -15,6 +15,7 @@ class ResourceContentType(str, Enum):
     IMAGE = "image"
     VIDEO = "video"
     AUDIO = "audio"
+    BINARY = "binary"
 
 
 class ContextType(str, Enum):

{openviking-0.1.10 → openviking-0.1.11}/openviking/parse/__init__.py

@@ -6,7 +6,7 @@ from openviking.parse.base import NodeType, ParseResult, ResourceNode, create_pa
 from openviking.parse.converter import DocumentConverter
 from openviking.parse.custom import CallbackParserWrapper, CustomParserProtocol, CustomParserWrapper
 from openviking.parse.parsers.base_parser import BaseParser
-from openviking.parse.parsers.code import CodeParser
+from openviking.parse.parsers.code import CodeRepositoryParser
 from openviking.parse.parsers.html import HTMLParser
 from openviking.parse.parsers.markdown import MarkdownParser
 from openviking.parse.parsers.pdf import PDFParser
@@ -27,7 +27,7 @@ __all__ = [
     "MarkdownParser",
     "PDFParser",
     "HTMLParser",
-    "CodeParser",
+    "CodeRepositoryParser",
     "DocumentConverter",
     # Custom parser support
     "CustomParserProtocol",

{openviking-0.1.10 → openviking-0.1.11}/openviking/parse/parsers/README.md

@@ -138,8 +138,8 @@ L1: """
 
 纯文本解析器，支持多种文本格式。对于结构化格式（JSON、YAML、XML）会尝试提取结构化信息。
 
-### 5. CodeParser (`code.py`)
-**支持格式**: `.py`, `.js`, `.ts`, `.java`, `.cpp`, `.c`, `.go`, `.rs`, `.php`, `.rb`, `.cs`, `.swift`, `.kt`, `.scala`
+### 5. CodeRepositoryParser (`code/*`)
+**支持来源**: github 代码仓库等
 
 代码解析器，支持语法高亮和代码结构分析。能识别函数、类、方法等代码元素。
 
@@ -187,7 +187,7 @@ class ParserRegistry:
         self.register("markdown", MarkdownParser())
         self.register("pdf", PDFParser())
         self.register("html", HTMLParser())
-        self.register("code", CodeParser())
+        self.register("code", CodeRepositoryParser())
     
     def get_parser_for_file(self, path: Union[str, Path]) -> Optional[BaseParser]:
         """根据文件扩展名获取合适的解析器"""

openviking-0.1.11/openviking/parse/parsers/__init__.py

@@ -0,0 +1,20 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+from .base_parser import BaseParser
+from .code import CodeRepositoryParser
+from .html import HTMLParser, URLType, URLTypeDetector
+from .markdown import MarkdownParser
+from .pdf import PDFParser
+from .text import TextParser
+
+__all__ = [
+    "BaseParser",
+    "CodeRepositoryParser",
+    "HTMLParser",
+    "URLType",
+    "URLTypeDetector",
+    "MarkdownParser",
+    "PDFParser",
+    "TextParser",
+]

openviking-0.1.11/openviking/parse/parsers/code/README.md

@@ -0,0 +1,170 @@
+# 代码解析方案 (Code Parser)
+
+OpenViking 通过 **Code Parser** 模块实现对代码仓库的整体解析与理解。与普通文档的拆解式处理不同，代码解析采用了基于目录结构的整体映射策略，旨在保持代码项目的完整上下文。
+
+## 概览
+
+| 特性 | 策略 | 说明 |
+|------|------|------|
+| **解析粒度** | 文件级 | 不进行 Chunking 拆分，保持单文件完整性 |
+| **目录映射** | 1:1 映射 | 本地目录结构直接映射为 Viking URI 路径 |
+| **处理模式** | 异步处理 | Parser 负责搬运，SemanticProcessor 负责理解 |
+| **元数据** | 自动提取 | 提取语言、依赖、符号定义等基础信息 |
+
+## 核心设计思考
+
+代码仓库作为一种特殊的资源类型，具有以下显著特征，这些特征直接决定了我们的技术方案：
+
+1.  **文件粒度适中**：大多数代码文件（KB 级）都在大模型上下文窗口范围内（<10k tokens），无需像长文档那样进行物理切分。
+2.  **结构即语义**：代码的目录结构（Directory Structure）本身就蕴含了模块划分、层级依赖等重要架构信息，必须严格保留。
+3.  **高频迭代**：代码变动频繁，系统需支持增量更新，避免重复索引未变动的文件。
+4.  **元数据丰富**：代码中的注释、DocString、Import 语句等包含了高密度的语义信息。
+
+## 上下文映射体系
+
+我们将代码仓库映射到 OpenViking 的标准分层描述体系中。
+
+### 1. Viking URI 映射
+
+假设用户导入了 `OpenViking` 仓库：
+
+```python
+client.add_resource(
+    "https://github.com/volcengine/OpenViking",
+    target="viking://resources/github/volcengine/OpenViking"
+)
+```
+
+系统将生成如下标准化的目录树结构，能够完整体现深层级的文件路径：
+
+```text
+viking://resources/github/volcengine/OpenViking/
+├── .abstract.md        # L0: 项目级摘要
+├── .overview.md        # L1: 项目级概览
+├── docs/
+│   ├── .abstract.md
+│   ├── .overview.md
+│   ├── zh/...
+│   └── en/...
+├── src/
+│   ├── .abstract.md
+│   ├── .overview.md
+│   └── index/          # 深层目录结构
+│       ├── .abstract.md
+│       ├── .overview.md
+│       └── index/      # 更深层的子模块
+│           ├── .abstract.md
+│           ├── .overview.md
+│           ├── index_engine.cpp    # L2: 具体代码文件（C++）
+│           └── ...
+└── openviking/
+    ├── .abstract.md
+    ├── .overview.md
+    └── ...
+```
+
+在这颗目录树中，每一层目录都会有一个 `.abstract.md` 文件和 `.overview.md` 文件：
+*   `.abstract.md`：目录的摘要，介绍本目录的功能和在项目中的作用。
+*   `.overview.md`：目录的概览，介绍本目录的文件结构、关键实体的位置等。
+
+### 2. 语义层级 (Context Layers)
+
+*   **L0 (Abstract)**：目录的简短功能描述，用于快速检索。
+*   **L1 (Overview)**：目录的详细概览，包含文件结构分析、关键类/函数索引。
+*   **L2 (Detail)**：原始代码文件内容。对于代码文件，我们**不进行拆分**，直接存储完整内容。
+
+## 数据处理原则
+
+1. 本方案对于任意编程语言的代码仓库均适用，不应该特殊处理任意编程语言的差异性，需要考虑策略足够通用。
+2. 对于代码仓库中的文档，除了图片以外，不要让大模型处理文本以外的其他模态内容，如视频、音频等。
+   - **说明**：".md"、".txt"、".rst" 等纯文本格式的文档文件**会被处理**，因为它们属于"文本内容"
+   - **排除**：视频（.mp4, .mov, .avi 等）、音频（.mp3, .wav, .m4a 等）等非文本格式**不会被处理**
+3. 可以忽略代码仓库中的隐藏文件，如 .git 文件夹下面的内容，__pycache__ 文件夹下面的内容等。
+4. 对于代码仓库中的符号链接，我们应当忽略并记录其目标路径，而不是直接解析符号链接。
+5. 对于代码仓库中的子目录，我们应当递归地处理，确保所有包含代码的目录，都被正确映射到 Viking URI 路径。
+
+## 技术实现方案
+
+### 1. 仓库识别与拉取
+
+扩展 `URLTypeDetector` 以支持代码仓库识别：
+
+*   **识别逻辑**：检测 URL 是否为 GitHub/GitLab 一级仓库地址（如 `https://github.com/org/repo` 或 `*.git`）。
+*   **拉取策略**：
+    *   **Git Clone**：优先使用 `git clone --depth 1` 进行浅克隆，速度最快。
+    *   **Zip Download**：作为降级方案，下载 `main.zip` 或 `master.zip`。
+*   **过滤机制**：内置过滤规则，自动忽略 `.git`, `.idea`, `__pycache__`, `node_modules` 等非代码资源。
+
+### 2. 解析流程 (CodeRepositoryParser)
+
+解析器遵循 V5.0 的异步处理架构：
+
+1.  **物理搬运 (Parser Phase)**：
+    *   将拉取到的代码仓库（经过过滤）完整上传到 `viking://temp/{uuid}/` 临时目录。
+    *   在此阶段**不进行**任何 LLM 调用，确保 `add_resource` 接口能快速返回。
+    *   仅进行基础的静态分析（如文件类型识别）。
+
+2.  **异步理解 (Semantic Phase)**：
+    *   `TreeBuilder` 将临时目录移入正式路径（如 `viking://resources/...`）。
+    *   系统自动生成 `SemanticMsg` 并推入 `SemanticQueue`。
+    *   后台 `SemanticProcessor` 消费消息，遍历目录树，异步生成各级目录的 `.abstract.md` 和 `.overview.md`。
+
+### 3. 使用示例
+
+```python
+# 导入代码仓库
+client.add_resource(
+    "https://github.com/volcengine/OpenViking",
+    target="viking://resources/github/volcengine/OpenViking",
+    reason="引入 OpenViking 源码作为参考"
+)
+
+# 搜索代码逻辑
+results = client.find(
+    "OpenViking 和 VikingDB 的关系是什么？",
+    target_uri="viking://resources/github/volcengine/OpenViking/OpenViking/docs/zh/"
+)
+```
+
+> 考虑到当前性能不佳，可以用小一点的仓库测试：https://github.com/msgpack/msgpack-python
+
+## 实现细节
+
+### 文件过滤规则
+
+代码解析器实现了以下过滤规则：
+
+1. **隐藏目录忽略**：自动忽略 `.git`, `.idea`, `__pycache__`, `node_modules` 等非代码目录
+2. **二进制文件忽略**：跳过 `.pyc`, `.so`, `.dll`, `.exe`, `.bin` 等编译文件
+3. **媒体文件忽略**：不处理视频（.mp4, .mov, .avi 等）、音频（.mp3, .wav, .m4a 等）等非文本内容
+4. **文档文件处理**：`.md`, `.txt`, `.rst` 等纯文本格式的文档文件**会被处理**，因为它们属于"文本内容"
+5. **符号链接处理**：检测并跳过符号链接，记录目标路径但不解析内容
+6. **文件大小限制**：跳过大于 10MB 的文件和零字节文件
+
+### 文件类型检测
+
+解析器包含辅助方法 `_detect_file_type()` 用于检测文件类型，可返回：
+- `"code"`：编程语言文件（.py, .java, .js, .cpp 等）
+- `"documentation"`：文档文件（.md, .txt, .rst 等）
+- `"other"`：其他文本文件
+- `"binary"`：二进制文件（已通过 `IGNORE_EXTENSIONS` 过滤）
+
+### 测试验证
+
+包含完整的测试文件 `tests/misc/test_code_parser.py` 验证：
+- `IGNORE_DIRS` 包含所有必需的目录
+- `IGNORE_EXTENSIONS` 包含所有必需的格式
+- 符号链接处理正确实现
+- 文件类型检测逻辑准确
+
+### 优化 TODO
+- 支持采用更轻量的模型进行文件摘要，加快处理速度
+- 设计长任务的追踪机制，帮助观测任务队列中的任务归属，提供处理任务的统计信息
+- 支持增量解析，只解析新增或变动的文件，避免重复解析已处理文件
+- 大幅提升端到端的处理性能！
+
+## 相关文档
+
+*   [上下文类型](docs/zh/concepts/02-context-types.md)
+*   [Viking URI](docs/zh/concepts/03-viking-uri.md)
+*   [上下文层级](docs/zh/concepts/04-context-layers.md)

openviking-0.1.11/openviking/parse/parsers/code/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+from .code import CodeRepositoryParser
+
+__all__ = [
+    "CodeRepositoryParser",
+]

openviking-0.1.11/openviking/parse/parsers/code/code.py

@@ -0,0 +1,363 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Code Repository Parser.
+
+Handles git repositories and zip archives of codebases.
+Implements V5.0 asynchronous architecture:
+- Physical move (Clone -> Temp VikingFS)
+- No LLM generation in parser phase
+"""
+
+import asyncio
+import os
+import shutil
+import tempfile
+import time
+from pathlib import Path
+from typing import Any, List, Optional, Union
+
+from openviking.parse.base import (
+    NodeType,
+    ParseResult,
+    ResourceNode,
+    create_parse_result,
+)
+from openviking.parse.parsers.base_parser import BaseParser
+from openviking.utils.logger import get_logger
+
+from openviking.parse.parsers.constants import (
+    CODE_EXTENSIONS,
+    DOCUMENTATION_EXTENSIONS,
+    FILE_TYPE_CODE,
+    FILE_TYPE_DOCUMENTATION,
+    FILE_TYPE_OTHER,
+    IGNORE_DIRS,
+    IGNORE_EXTENSIONS,
+    ADDITIONAL_TEXT_EXTENSIONS,
+    TEXT_ENCODINGS,
+    UTF8_VARIANTS,
+)
+
+logger = get_logger(__name__)
+
+
+class CodeRepositoryParser(BaseParser):
+    """
+    Parser for code repositories (Git/Zip).
+
+    Features:
+    - Shallow clone for Git repositories
+    - Automatic filtering of non-code directories (.git, node_modules, etc.)
+    - Direct mapping to VikingFS temp directory
+    - Preserves directory structure without chunking
+    """
+
+    # Class constants imported from constants.py
+    IGNORE_DIRS = IGNORE_DIRS
+    IGNORE_EXTENSIONS = IGNORE_EXTENSIONS
+
+    @property
+    def supported_extensions(self) -> List[str]:
+        # This parser is primarily invoked by URLTypeDetector, not by file extension
+        return [".git", ".zip"]
+
+    def _detect_file_type(self, file_path: Path) -> str:
+        """
+        Detect file type based on extension for potential metadata tagging.
+
+        Returns:
+            "code" for programming language files
+            "documentation" for documentation files (md, txt, rst, etc.)
+            "other" for other text files
+            "binary" for binary files (already filtered by IGNORE_EXTENSIONS)
+        """
+        extension = file_path.suffix.lower()
+
+        if extension in CODE_EXTENSIONS:
+            return FILE_TYPE_CODE
+        elif extension in DOCUMENTATION_EXTENSIONS:
+            return FILE_TYPE_DOCUMENTATION
+        else:
+            # For other text files not in the lists
+            return FILE_TYPE_OTHER
+
+    async def parse(self, source: Union[str, Path], instruction: str = "", **kwargs) -> ParseResult:
+        """
+        Parse code repository.
+
+        Args:
+            source: Repository URL (git/http) or local zip path
+            instruction: Processing instruction (unused in parser phase)
+            **kwargs: Additional arguments
+
+        Returns:
+            ParseResult with temp_dir_path pointing to the uploaded content
+        """
+        start_time = time.time()
+        source_str = str(source)
+        temp_local_dir = None
+
+        try:
+            # 1. Prepare local temp directory
+            temp_local_dir = tempfile.mkdtemp(prefix="ov_repo_")
+            logger.info(f"Created local temp dir: {temp_local_dir}")
+
+            # 2. Fetch content (Clone or Extract)
+            repo_name = "repository"
+            if source_str.startswith(("http://", "https://", "git://", "ssh://")):
+                repo_name = await self._git_clone(source_str, temp_local_dir)
+            elif str(source).endswith(".zip"):
+                repo_name = await self._extract_zip(source_str, temp_local_dir)
+            else:
+                raise ValueError(f"Unsupported source for CodeRepositoryParser: {source}")
+
+            # 3. Create VikingFS temp URI
+            viking_fs = self._get_viking_fs()
+            temp_viking_uri = self._create_temp_uri()
+            # The structure in temp should be: viking://temp/{uuid}/{repo_name}/...
+            target_root_uri = f"{temp_viking_uri}/{repo_name}"
+
+            logger.info(f"Uploading to VikingFS: {target_root_uri}")
+
+            # 4. Upload to VikingFS (filtering on the fly)
+            file_count = await self._upload_directory(
+                Path(temp_local_dir), target_root_uri, viking_fs
+            )
+
+            logger.info(f"Uploaded {file_count} files to {target_root_uri}")
+
+            # 5. Create result
+            # Root node is just a placeholder, TreeBuilder relies on temp_dir_path
+            root = ResourceNode(
+                type=NodeType.ROOT,
+                content_path=None,
+                meta={"name": repo_name, "type": "repository"},
+            )
+
+            result = create_parse_result(
+                root=root,
+                source_path=source_str,
+                source_format="repository",
+                parser_name="CodeRepositoryParser",
+                parse_time=time.time() - start_time,
+            )
+            result.temp_dir_path = temp_viking_uri  # Points to parent of repo_name
+            result.meta["file_count"] = file_count
+            result.meta["repo_name"] = repo_name
+
+            return result
+
+        except Exception as e:
+            logger.error(f"Failed to parse repository {source}: {e}", exc_info=True)
+            return create_parse_result(
+                root=ResourceNode(type=NodeType.ROOT, content_path=None),
+                source_path=source_str,
+                source_format="repository",
+                parser_name="CodeRepositoryParser",
+                parse_time=time.time() - start_time,
+                warnings=[f"Failed to parse repository: {str(e)}"],
+            )
+
+        finally:
+            # Cleanup local temp dir
+            if temp_local_dir and os.path.exists(temp_local_dir):
+                try:
+                    shutil.rmtree(temp_local_dir)
+                    logger.debug(f"Cleaned up local temp dir: {temp_local_dir}")
+                except Exception as e:
+                    logger.warning(f"Failed to cleanup local temp dir {temp_local_dir}: {e}")
+
+    async def parse_content(
+        self, content: str, source_path: Optional[str] = None, instruction: str = "", **kwargs
+    ) -> ParseResult:
+        """Not supported for repositories."""
+        raise NotImplementedError("CodeRepositoryParser does not support parse_content")
+
+    async def _git_clone(self, url: str, target_dir: str) -> str:
+        """
+        Clone git repository.
+
+        Returns:
+            Repository name (e.g. "OpenViking" from "https://.../OpenViking.git")
+        """
+        # Extract repo name from URL
+        clean_url = url.rstrip("/")
+        if clean_url.endswith(".git"):
+            name = clean_url.split("/")[-1][:-4]
+        else:
+            name = clean_url.split("/")[-1]
+
+        # Sanitize name
+        name = "".join(c if c.isalnum() or c in "-_" else "_" for c in name)
+        if not name:
+            name = "repository"
+
+        # Clone into a subdirectory to keep structure clean
+        # But here we clone content directly into target_dir?
+        # Actually, git clone <url> <dir> clones INTO <dir>.
+        # But if we want the repo name directory to exist in VikingFS, we should clone into target_dir/name?
+        # No, parse logic says:
+        # temp_local_dir contains the files (e.g. .git, src, README)
+        # We upload temp_local_dir content to viking://temp/{uuid}/{repo_name}/
+
+        # So we clone current content directly into temp_local_dir
+        # git clone --depth 1 url target_dir
+
+        logger.info(f"Cloning {url} to {target_dir}...")
+
+        proc = await asyncio.create_subprocess_exec(
+            "git",
+            "clone",
+            "--depth",
+            "1",
+            "--recursive",  # Also clone submodules? Maybe risky for huge repos
+            url,
+            target_dir,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        stdout, stderr = await proc.communicate()
+
+        if proc.returncode != 0:
+            error_msg = stderr.decode()
+            raise RuntimeError(f"Git clone failed: {error_msg}")
+
+        return name
+
+    async def _extract_zip(self, zip_path: str, target_dir: str) -> str:
+        """Extract zip file."""
+        import zipfile
+
+        # We assume it's a local path if passed here?
+        # Actually logic in parse() handles local path check before calling here?
+        # Or if it's a URL ending in zip, HTMLParser might have downloaded it?
+        # Wait, HTMLParser handles download. If we are here, source IS a path or URL.
+        # If it's a URL, we need to download it first?
+        # CodeRepositoryParser is designed to handle "source" which can be URL.
+        # So I need to download zip if it is a URL.
+
+        if zip_path.startswith(("http://", "https://")):
+            # TODO: implement download logic or rely on caller?
+            # For now, assume it's implemented if needed, but raise error as strictly we only support git URL for now as per plan
+            raise NotImplementedError(
+                "Zip URL download not yet implemented in CodeRepositoryParser"
+            )
+
+        path = Path(zip_path)
+        name = path.stem
+
+        with zipfile.ZipFile(zip_path, "r") as zip_ref:
+            zip_ref.extractall(target_dir)
+
+        return name
+
+    async def _upload_directory(self, local_dir: Path, viking_uri_base: str, viking_fs: Any) -> int:
+        """
+        Recursively upload directory to VikingFS.
+
+        Args:
+            local_dir: Local source directory
+            viking_uri_base: Target Viking URI
+            viking_fs: VikingFS instance
+
+        Returns:
+            Number of uploaded files
+        """
+        count = 0
+
+        # Ensure target directory exists (although write_file handles parents, mkdir ensures root exists)
+        await viking_fs.mkdir(viking_uri_base, exist_ok=True)
+
+        for root, dirs, files in os.walk(local_dir):
+            # Modify dirs in-place to skip ignored directories
+            dirs[:] = [d for d in dirs if d not in IGNORE_DIRS and not d.startswith(".")]
+
+            for file in files:
+                if file.startswith("."):
+                    continue
+
+                file_path = Path(root) / file
+
+                file_path = Path(root) / file
+
+                # Calculate relative path for URI construction
+                rel_path = file_path.relative_to(local_dir)
+                rel_path_str = str(rel_path).replace(os.sep, "/")
+
+                # Check if it's a symbolic link (skip and log)
+                if os.path.islink(file_path):
+                    target = os.readlink(file_path)
+                    logger.info(f"Ignoring symbolic link {rel_path_str}: {file_path} -> {target}")
+                    continue
+
+                # Check extension
+                if file_path.suffix.lower() in IGNORE_EXTENSIONS:
+                    continue
+
+                # Check file size (skip > 10MB)
+                try:
+                    size = file_path.stat().st_size
+                    if size > 10 * 1024 * 1024:
+                        logger.warning(f"Skipping large file {file}: {size} bytes")
+                        continue
+                    if size == 0:
+                        continue
+                except OSError:
+                    continue
+
+                # Construct Viking URI: base + rel_path
+                target_uri = f"{viking_uri_base}/{rel_path_str}"
+
+                # Read and upload
+                try:
+                    content = file_path.read_bytes()
+
+                    # Check if this is a text file that might need encoding conversion
+                    extension = file_path.suffix.lower()
+                    is_text_file = (
+                        extension in CODE_EXTENSIONS
+                        or extension in DOCUMENTATION_EXTENSIONS
+                        or extension in ADDITIONAL_TEXT_EXTENSIONS
+                    )
+
+                    if is_text_file:
+                        # Try to detect encoding and convert to UTF-8
+                        try:
+                            detected_encoding = None
+                            for encoding in TEXT_ENCODINGS:
+                                try:
+                                    # Try to decode with this encoding
+                                    decoded = content.decode(encoding)
+                                    detected_encoding = encoding
+                                    break
+                                except UnicodeDecodeError:
+                                    continue
+
+                            if detected_encoding and detected_encoding not in UTF8_VARIANTS:
+                                # Convert to UTF-8
+                                decoded = content.decode(detected_encoding, errors="replace")
+                                content = decoded.encode("utf-8")
+                                logger.debug(
+                                    f"Converted {rel_path_str} from {detected_encoding} to UTF-8"
+                                )
+
+                        except Exception as encode_error:
+                            # If encoding detection/conversion fails, use original bytes
+                            logger.warning(
+                                f"Encoding detection failed for {file_path}: {encode_error}"
+                            )
+
+                    # Use write_file_bytes for safety
+                    await viking_fs.write_file_bytes(target_uri, content)
+
+                    # TODO: Add metadata tagging when VikingFS supports it
+                    # file_type = self._detect_file_type(file_path)
+                    # await viking_fs.set_metadata(target_uri, {"file_type": file_type})
+
+                    count += 1
+                except Exception as e:
+                    logger.warning(f"Failed to upload {file_path}: {e}")
+
+        return count