> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/volcengine/OpenViking/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Complete Python SDK reference with all methods, signatures, and examples

The OpenViking Python SDK provides both synchronous and asynchronous clients for embedded and HTTP modes.

## Installation

```bash theme={null}
pip install openviking
```

## Client Types

| Client            | Mode     | Use Case                         |
| ----------------- | -------- | -------------------------------- |
| `SyncOpenViking`  | Embedded | Single-process apps, scripts     |
| `AsyncOpenViking` | Embedded | Async apps with local storage    |
| `SyncHTTPClient`  | HTTP     | Connect to remote server (sync)  |
| `AsyncHTTPClient` | HTTP     | Connect to remote server (async) |

<Info>
  `OpenViking` is an alias for `SyncOpenViking` for convenience.
</Info>

## Quick Start

<Tabs>
  <Tab title="Embedded Mode">
    ```python theme={null}
    import openviking as ov

    # Initialize client
    client = ov.OpenViking(path="./data")
    client.initialize()

    # Add resource
    result = client.add_resource(
        path="https://example.com/docs",
        wait=True
    )

    # Search
    results = client.find("how to use openviking")
    for r in results.resources:
        print(f"{r.uri}: {r.score}")

    client.close()
    ```
  </Tab>

  <Tab title="HTTP Mode">
    ```python theme={null}
    import openviking as ov

    # Connect to server
    client = ov.SyncHTTPClient(
        url="http://localhost:1933",
        api_key="your-key",
        agent_id="my-agent"
    )

    client.initialize()

    # Add resource
    result = client.add_resource(
        path="https://example.com/docs",
        wait=True
    )

    # Search
    results = client.find("how to use openviking")

    client.close()
    ```
  </Tab>

  <Tab title="Async">
    ```python theme={null}
    import openviking as ov

    async def main():
        client = ov.AsyncOpenViking(path="./data")
        await client.initialize()
        
        result = await client.add_resource(
            path="https://example.com/docs",
            wait=True
        )
        
        results = await client.find("how to use openviking")
        
        await client.close()

    import asyncio
    asyncio.run(main())
    ```
  </Tab>
</Tabs>

## Client Initialization

### SyncOpenViking / AsyncOpenViking

```python theme={null}
client = ov.SyncOpenViking(path: Optional[str] = None)
```

**Parameters:**

| Parameter | Type  | Description                              | Default |
| --------- | ----- | ---------------------------------------- | ------- |
| `path`    | `str` | Local storage path (overrides `ov.conf`) | `None`  |

### SyncHTTPClient / AsyncHTTPClient

```python theme={null}
client = ov.SyncHTTPClient(
    url: Optional[str] = None,
    api_key: Optional[str] = None,
    agent_id: Optional[str] = None,
    timeout: float = 60.0
)
```

**Parameters:**

| Parameter  | Type    | Description                                         | Default |
| ---------- | ------- | --------------------------------------------------- | ------- |
| `url`      | `str`   | Server URL (auto-loads from `ovcli.conf` if `None`) | `None`  |
| `api_key`  | `str`   | API key (auto-loads from `ovcli.conf` if `None`)    | `None`  |
| `agent_id` | `str`   | Agent identifier for isolation                      | `None`  |
| `timeout`  | `float` | HTTP request timeout in seconds                     | `60.0`  |

## Core Methods

### Lifecycle

<AccordionGroup>
  <Accordion title="initialize()" icon="play">
    ```python theme={null}
    client.initialize() -> None
    ```

    Initialize storage and indexes. Must be called before other operations.

    **Example:**

    ```python theme={null}
    client = ov.OpenViking(path="./data")
    client.initialize()
    ```
  </Accordion>

  <Accordion title="close()" icon="stop">
    ```python theme={null}
    client.close() -> None
    ```

    Close client and release resources.

    **Example:**

    ```python theme={null}
    try:
        client.initialize()
        # ... operations ...
    finally:
        client.close()
    ```
  </Accordion>

  <Accordion title="reset()" icon="rotate-right">
    ```python theme={null}
    SyncOpenViking.reset() -> None  # Class method
    ```

    Reset singleton instance (mainly for testing).

    **Example:**

    ```python theme={null}
    SyncOpenViking.reset()
    client = ov.OpenViking(path="./new_data")
    ```
  </Accordion>
</AccordionGroup>

### Resource Management

<AccordionGroup>
  <Accordion title="add_resource()" icon="plus">
    ```python theme={null}
    client.add_resource(
        path: str,
        target: Optional[str] = None,
        reason: str = "",
        instruction: str = "",
        wait: bool = False,
        timeout: float = None,
        build_index: bool = True,
        summarize: bool = False,
        **kwargs
    ) -> Dict[str, Any]
    ```

    Add a resource (file, URL, or directory) to OpenViking.

    **Parameters:**

    | Parameter     | Type    | Description                                 |
    | ------------- | ------- | ------------------------------------------- |
    | `path`        | `str`   | Local file path or URL                      |
    | `target`      | `str`   | Target path in VikingFS (e.g., `"kb/docs"`) |
    | `reason`      | `str`   | Context/reason for adding                   |
    | `instruction` | `str`   | Processing instruction                      |
    | `wait`        | `bool`  | Wait for processing to complete             |
    | `timeout`     | `float` | Wait timeout in seconds                     |
    | `build_index` | `bool`  | Build vector index immediately              |
    | `summarize`   | `bool`  | Generate summary                            |

    **Returns:**

    ```python theme={null}
    {
        "root_uri": "viking://resources/example",
        "status": "processing"
    }
    ```

    **Example:**

    ```python theme={null}
    # Add URL and wait
    result = client.add_resource(
        path="https://github.com/volcengine/OpenViking/README.md",
        reason="Project documentation",
        wait=True,
        timeout=120
    )
    root_uri = result["root_uri"]

    # Add local directory
    result = client.add_resource(
        path="./docs",
        target="kb/project-docs",
        wait=True
    )
    ```
  </Accordion>

  <Accordion title="add_skill()" icon="wand-magic-sparkles">
    ```python theme={null}
    client.add_skill(
        data: Any,
        wait: bool = False,
        timeout: float = None
    ) -> Dict[str, Any]
    ```

    Add a skill to OpenViking.

    **Example:**

    ```python theme={null}
    skill_data = {
        "name": "example-skill",
        "description": "Example skill"
    }
    result = client.add_skill(skill_data, wait=True)
    ```
  </Accordion>

  <Accordion title="rm()" icon="trash">
    ```python theme={null}
    client.rm(
        uri: str,
        recursive: bool = False
    ) -> None
    ```

    Delete a resource.

    **Example:**

    ```python theme={null}
    # Delete file
    client.rm("viking://resources/example.md")

    # Delete directory recursively
    client.rm("viking://resources/docs", recursive=True)
    ```
  </Accordion>

  <Accordion title="mv()" icon="arrows-left-right">
    ```python theme={null}
    client.mv(
        from_uri: str,
        to_uri: str
    ) -> None
    ```

    Move or rename a resource.

    **Example:**

    ```python theme={null}
    client.mv(
        "viking://resources/old.md",
        "viking://resources/new.md"
    )
    ```
  </Accordion>

  <Accordion title="wait_processed()" icon="hourglass">
    ```python theme={null}
    client.wait_processed(
        timeout: float = None
    ) -> Dict[str, Any]
    ```

    Wait for all queued processing to complete.

    **Example:**

    ```python theme={null}
    client.add_resource("https://example.com/large-doc")
    client.wait_processed(timeout=300)  # Wait up to 5 minutes
    ```
  </Accordion>
</AccordionGroup>

### Search and Retrieval

<AccordionGroup>
  <Accordion title="find()" icon="magnifying-glass">
    ```python theme={null}
    client.find(
        query: str,
        target_uri: str = "",
        limit: int = 10,
        score_threshold: Optional[float] = None,
        filter: Optional[Dict] = None
    ) -> FindResult
    ```

    Semantic search (quick retrieval without session context).

    **Parameters:**

    | Parameter         | Type    | Description              |
    | ----------------- | ------- | ------------------------ |
    | `query`           | `str`   | Search query             |
    | `target_uri`      | `str`   | Scope to directory       |
    | `limit`           | `int`   | Max results              |
    | `score_threshold` | `float` | Minimum similarity score |
    | `filter`          | `dict`  | Metadata filters         |

    **Returns:** `FindResult` with:

    * `resources`: List of `SearchResult` objects
    * Each `SearchResult` has: `uri`, `score`, `content`

    **Example:**

    ```python theme={null}
    # Basic search
    results = client.find("how to deploy openviking")
    for r in results.resources:
        print(f"{r.uri}: {r.score:.4f}")

    # Search with filters
    results = client.find(
        query="authentication guide",
        target_uri="viking://resources/docs",
        limit=5,
        score_threshold=0.7
    )
    ```
  </Accordion>

  <Accordion title="search()" icon="magnifying-glass-plus">
    ```python theme={null}
    client.search(
        query: str,
        target_uri: str = "",
        session: Optional[Session] = None,
        session_id: Optional[str] = None,
        limit: int = 10,
        score_threshold: Optional[float] = None,
        filter: Optional[Dict] = None
    ) -> FindResult
    ```

    Context-aware search with session (intent analysis + hierarchical retrieval).

    **Example:**

    ```python theme={null}
    session = client.session()
    run_async(session.add_message(role="user", content="Tell me about OpenViking"))

    # Search with session context
    results = client.search(
        query="how to use it",
        session=session,
        limit=5
    )
    ```
  </Accordion>

  <Accordion title="grep()" icon="text-slash">
    ```python theme={null}
    client.grep(
        uri: str,
        pattern: str,
        case_insensitive: bool = False
    ) -> Dict
    ```

    Content pattern search (regex).

    **Example:**

    ```python theme={null}
    # Case-sensitive search
    results = client.grep(
        uri="viking://resources",
        pattern="OpenViking"
    )

    # Case-insensitive
    results = client.grep(
        uri="viking://resources",
        pattern="openviking",
        case_insensitive=True
    )
    ```
  </Accordion>

  <Accordion title="glob()" icon="asterisk">
    ```python theme={null}
    client.glob(
        pattern: str,
        uri: str = "viking://"
    ) -> Dict
    ```

    File pattern matching.

    **Example:**

    ```python theme={null}
    # Find all markdown files
    results = client.glob("**/*.md", uri="viking://resources")
    for match in results["matches"]:
        print(match)

    # Find specific pattern
    results = client.glob("**/config*.json")
    ```
  </Accordion>
</AccordionGroup>

### File System Operations

<AccordionGroup>
  <Accordion title="ls()" icon="list">
    ```python theme={null}
    client.ls(
        uri: str,
        simple: bool = False,
        recursive: bool = False
    ) -> List[Any]
    ```

    List directory contents.

    **Example:**

    ```python theme={null}
    # Basic listing
    entries = client.ls("viking://resources")
    for entry in entries:
        print(f"{entry['name']} - {entry['isDir']}")

    # Simple mode (paths only)
    paths = client.ls("viking://resources", simple=True)

    # Recursive
    all_entries = client.ls("viking://resources", recursive=True)
    ```
  </Accordion>

  <Accordion title="tree()" icon="folder-tree">
    ```python theme={null}
    client.tree(
        uri: str,
        **kwargs
    ) -> Dict
    ```

    Get directory tree structure.

    **Example:**

    ```python theme={null}
    tree = client.tree("viking://resources")
    print(f"Nodes: {len(tree.get('children', []))}")
    ```
  </Accordion>

  <Accordion title="mkdir()" icon="folder-plus">
    ```python theme={null}
    client.mkdir(uri: str) -> None
    ```

    Create a directory.

    **Example:**

    ```python theme={null}
    client.mkdir("viking://resources/new-folder")
    ```
  </Accordion>

  <Accordion title="stat()" icon="info">
    ```python theme={null}
    client.stat(uri: str) -> Dict
    ```

    Get resource metadata.

    **Example:**

    ```python theme={null}
    info = client.stat("viking://resources/example.md")
    print(f"Size: {info['size']}")
    print(f"Modified: {info['modified']}")
    ```
  </Accordion>
</AccordionGroup>

### Content Access

<AccordionGroup>
  <Accordion title="read()" icon="file">
    ```python theme={null}
    client.read(
        uri: str,
        offset: int = 0,
        limit: int = -1
    ) -> str
    ```

    Read L2 (full content).

    **Example:**

    ```python theme={null}
    # Read entire file
    content = client.read("viking://resources/example.md")

    # Read with pagination
    content = client.read("viking://resources/large.txt", offset=0, limit=1000)
    ```
  </Accordion>

  <Accordion title="abstract()" icon="a">
    ```python theme={null}
    client.abstract(uri: str) -> str
    ```

    Read L0 abstract (\~100 token summary).

    **Example:**

    ```python theme={null}
    abstract = client.abstract("viking://resources/docs")
    print(f"Summary: {abstract}")
    ```
  </Accordion>

  <Accordion title="overview()" icon="magnifying-glass-chart">
    ```python theme={null}
    client.overview(uri: str) -> str
    ```

    Read L1 overview (\~2k token overview with navigation).

    **Example:**

    ```python theme={null}
    overview = client.overview("viking://resources/docs")
    print(overview)
    ```
  </Accordion>
</AccordionGroup>

## Session Management

<AccordionGroup>
  <Accordion title="session()" icon="message">
    ```python theme={null}
    client.session(
        session_id: Optional[str] = None,
        must_exist: bool = False
    ) -> Session
    ```

    Create new session or load existing.

    **Example:**

    ```python theme={null}
    # Create new session
    session = client.session()

    # Load existing
    session = client.session(session_id="abc123", must_exist=True)
    ```
  </Accordion>

  <Accordion title="session_exists()" icon="circle-check">
    ```python theme={null}
    client.session_exists(session_id: str) -> bool
    ```

    Check if session exists.

    **Example:**

    ```python theme={null}
    if client.session_exists("abc123"):
        session = client.session("abc123")
    ```
  </Accordion>

  <Accordion title="create_session()" icon="plus">
    ```python theme={null}
    client.create_session() -> Dict[str, Any]
    ```

    Create new session (returns dict).

    **Example:**

    ```python theme={null}
    result = client.create_session()
    session_id = result["session_id"]
    ```
  </Accordion>

  <Accordion title="list_sessions()" icon="list">
    ```python theme={null}
    client.list_sessions() -> List[Any]
    ```

    List all sessions.

    **Example:**

    ```python theme={null}
    sessions = client.list_sessions()
    for s in sessions:
        print(f"{s['session_id']}: {s['created_at']}")
    ```
  </Accordion>

  <Accordion title="get_session()" icon="eye">
    ```python theme={null}
    client.get_session(session_id: str) -> Dict[str, Any]
    ```

    Get session details.

    **Example:**

    ```python theme={null}
    details = client.get_session("abc123")
    print(f"Messages: {len(details['messages'])}")
    ```
  </Accordion>

  <Accordion title="delete_session()" icon="trash">
    ```python theme={null}
    client.delete_session(session_id: str) -> None
    ```

    Delete a session.

    **Example:**

    ```python theme={null}
    client.delete_session("abc123")
    ```
  </Accordion>

  <Accordion title="add_message()" icon="message-plus">
    ```python theme={null}
    client.add_message(
        session_id: str,
        role: str,
        content: str | None = None,
        parts: list[dict] | None = None
    ) -> Dict[str, Any]
    ```

    Add message to session.

    **Parameters:**

    * `role`: `"user"` or `"assistant"`
    * `content`: Text content (simple mode)
    * `parts`: Parts array for multimodal (TextPart, ContextPart, ToolPart)

    **Example:**

    ```python theme={null}
    # Simple text message
    client.add_message(
        session_id="abc123",
        role="user",
        content="Hello"
    )

    # With parts
    client.add_message(
        session_id="abc123",
        role="assistant",
        parts=[
            {"type": "text", "text": "Response"},
            {"type": "context", "uri": "viking://..."}
        ]
    )
    ```
  </Accordion>

  <Accordion title="commit_session()" icon="check">
    ```python theme={null}
    client.commit_session(session_id: str) -> Dict[str, Any]
    ```

    Commit session (archive and extract memories).

    **Example:**

    ```python theme={null}
    result = client.commit_session("abc123")
    print(f"Memories extracted: {result['memory_count']}")
    ```
  </Accordion>
</AccordionGroup>

## Relations

<AccordionGroup>
  <Accordion title="link()" icon="link">
    ```python theme={null}
    client.link(
        from_uri: str,
        uris: str | List[str],
        reason: str = ""
    ) -> None
    ```

    Create relation link(s).

    **Example:**

    ```python theme={null}
    # Single link
    client.link(
        "viking://resources/doc1.md",
        "viking://resources/doc2.md",
        reason="Related documentation"
    )

    # Multiple links
    client.link(
        "viking://resources/index.md",
        [
            "viking://resources/guide1.md",
            "viking://resources/guide2.md"
        ],
        reason="Index references"
    )
    ```
  </Accordion>

  <Accordion title="unlink()" icon="link-slash">
    ```python theme={null}
    client.unlink(
        from_uri: str,
        uri: str
    ) -> None
    ```

    Remove relation link.

    **Example:**

    ```python theme={null}
    client.unlink(
        "viking://resources/doc1.md",
        "viking://resources/doc2.md"
    )
    ```
  </Accordion>

  <Accordion title="relations()" icon="diagram-project">
    ```python theme={null}
    client.relations(uri: str) -> List[Dict[str, Any]]
    ```

    Get all relations for a resource.

    **Returns:**

    ```python theme={null}
    [
        {"uri": "viking://...", "reason": "Related doc"},
        {"uri": "viking://...", "reason": "Reference"}
    ]
    ```

    **Example:**

    ```python theme={null}
    rels = client.relations("viking://resources/doc.md")
    for rel in rels:
        print(f"{rel['uri']}: {rel['reason']}")
    ```
  </Accordion>
</AccordionGroup>

## Import/Export

<AccordionGroup>
  <Accordion title="export_ovpack()" icon="file-export">
    ```python theme={null}
    client.export_ovpack(
        uri: str,
        to: str
    ) -> str
    ```

    Export resource as .ovpack file.

    **Example:**

    ```python theme={null}
    output_path = client.export_ovpack(
        uri="viking://resources/docs",
        to="./backups/docs.ovpack"
    )
    print(f"Exported to: {output_path}")
    ```
  </Accordion>

  <Accordion title="import_ovpack()" icon="file-import">
    ```python theme={null}
    client.import_ovpack(
        file_path: str,
        target: str,
        force: bool = False,
        vectorize: bool = True
    ) -> str
    ```

    Import .ovpack file.

    **Example:**

    ```python theme={null}
    root_uri = client.import_ovpack(
        file_path="./backups/docs.ovpack",
        target="viking://resources/restored",
        vectorize=True
    )
    print(f"Imported to: {root_uri}")
    ```
  </Accordion>
</AccordionGroup>

## Health and Status

<AccordionGroup>
  <Accordion title="get_status()" icon="heart-pulse">
    ```python theme={null}
    client.get_status() -> Dict[str, Any]
    ```

    Get system status.

    **Example:**

    ```python theme={null}
    status = client.get_status()
    print(f"Healthy: {status['is_healthy']}")
    for name, info in status['components'].items():
        print(f"{name}: {info['is_healthy']}")
    ```
  </Accordion>

  <Accordion title="is_healthy()" icon="circle-check">
    ```python theme={null}
    client.is_healthy() -> bool
    ```

    Quick health check.

    **Example:**

    ```python theme={null}
    if client.is_healthy():
        print("System OK")
    else:
        print("System has issues")
    ```
  </Accordion>

  <Accordion title="observer" icon="eye">
    ```python theme={null}
    client.observer -> Observer
    ```

    Access component status.

    **Example:**

    ```python theme={null}
    queue = client.observer.queue
    print(f"Queue healthy: {queue['is_healthy']}")
    print(f"Queue size: {queue.get('queue_size', 0)}")

    vectordb = client.observer.vikingdb
    vlm = client.observer.vlm
    system = client.observer.system
    ```
  </Accordion>
</AccordionGroup>

## Complete Example

```python theme={null}
import openviking as ov
from openviking_cli.utils import run_async

# Initialize client
client = ov.SyncHTTPClient(
    url="http://localhost:1933",
    api_key="your-key",
    agent_id="demo-agent"
)

try:
    client.initialize()
    
    # Add resource
    result = client.add_resource(
        path="https://github.com/volcengine/OpenViking/README.md",
        reason="Project documentation"
    )
    root_uri = result["root_uri"]
    
    # Wait for processing
    client.wait_processed(timeout=120)
    
    # Read content layers
    abstract = client.abstract(root_uri)  # L0
    overview = client.overview(root_uri)  # L1
    content = client.read(root_uri)        # L2
    
    # Semantic search
    results = client.find(
        "how to install openviking",
        limit=5,
        score_threshold=0.7
    )
    
    for r in results.resources:
        print(f"{r.uri} (score: {r.score:.4f})")
    
    # Session workflow
    session = client.session()
    run_async(session.add_message(role="user", content="Tell me about OpenViking"))
    run_async(session.add_message(role="assistant", content="OpenViking is..."))
    
    # Context-aware search
    ctx_results = client.search(
        "how to use it",
        session=session,
        limit=3
    )
    
    # Commit session
    run_async(session.commit())
    
    # Check health
    if client.is_healthy():
        print("System healthy")
    
finally:
    client.close()
```

## Related Resources

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/guides/configuration">
    Client configuration and setup
  </Card>

  <Card title="CLI Usage" icon="terminal" href="/guides/cli-usage">
    Command-line interface guide
  </Card>

  <Card title="Authentication" icon="key" href="/guides/authentication">
    API key setup for HTTP mode
  </Card>

  <Card title="Deployment" icon="rocket" href="/guides/deployment">
    Deploy OpenViking Server
  </Card>
</CardGroup>