HCFS/docs/API_REFERENCE.md

# HCFS API Reference

## Overview

The HCFS API provides syscall-style functions for agents to navigate, query, and manipulate hierarchical context. All operations are designed to be familiar to agents accustomed to filesystem operations.

## Core Navigation API

### `context_cd(path: str) -> bool`

Change the current context directory. Similar to the shell `cd` command.

**Parameters:**
- `path`: Target path (absolute or relative)

**Returns:**
- `True` if path exists and is accessible
- `False` if path does not exist or is inaccessible

**Example:**
```python
# Navigate to project root
success = context_cd("/project")

# Navigate to subdirectory  
success = context_cd("src/models")

# Navigate up one level
success = context_cd("..")
```

### `context_pwd() -> str`

Get the current context working directory.

**Returns:**
- Current absolute path as string

**Example:**
```python
current_path = context_pwd()
# Returns: "/project/src/models"
```

### `context_ls(path: str = None) -> List[str]`

List available context paths at the specified directory.

**Parameters:**
- `path`: Directory path (default: current directory)

**Returns:**
- List of child path names

**Example:**
```python
# List current directory
paths = context_ls()
# Returns: ["models/", "utils/", "tests/", "README.md"]

# List specific directory
paths = context_ls("/project/docs")
# Returns: ["api/", "architecture/", "examples/"]
```

## Context Retrieval API

### `context_get(depth: int = 1, filters: dict = None) -> List[ContextBlob]`

Retrieve context blobs from current path and optionally parent paths.

**Parameters:**
- `depth`: How many levels up the hierarchy to include (1 = current only)
- `filters`: Optional filters (content_type, author, date_range, etc.)

**Returns:**
- List of `ContextBlob` objects ordered by relevance

**Example:**
```python
# Get context from current path only
context = context_get(depth=1)

# Get context from current path and 2 parent levels
context = context_get(depth=3)

# Get context with filters
context = context_get(
    depth=2, 
    filters={
        "content_type": "documentation",
        "author": "claude",
        "since": "2025-01-01"
    }
)
```

### `context_search(query: str, scope: str = None) -> List[ContextBlob]`

Perform semantic search across context blobs.

**Parameters:**
- `query`: Search query string
- `scope`: Path scope to limit search (default: current path and children)

**Returns:**
- List of `ContextBlob` objects ranked by relevance

**Example:**
```python
# Search within current scope
results = context_search("error handling patterns")

# Search within specific scope
results = context_search(
    "database connection", 
    scope="/project/src/models"
)
```

## Context Manipulation API

### `context_push(path: str, blob: ContextBlob) -> str`

Add or update context at the specified path.

**Parameters:**
- `path`: Target path for the context
- `blob`: ContextBlob object containing content and metadata

**Returns:**
- Blob ID of the created/updated context

**Example:**
```python
from hcfs.api import ContextBlob

# Create new context blob
blob = ContextBlob(
    content="This module handles user authentication",
    content_type="documentation",
    tags=["auth", "security", "users"],
    metadata={"priority": "high"}
)

# Push to specific path
blob_id = context_push("/project/src/auth.py", blob)
```

### `context_delete(path: str, blob_id: str = None) -> bool`

Delete context blob(s) at the specified path.

**Parameters:**
- `path`: Target path
- `blob_id`: Specific blob ID (if None, deletes all blobs at path)

**Returns:**
- `True` if deletion successful
- `False` if path/blob not found or permission denied

**Example:**
```python
# Delete specific blob
success = context_delete("/project/src/auth.py", blob_id)

# Delete all context at path
success = context_delete("/project/old_module/")
```

### `context_update(blob_id: str, updates: dict) -> bool`

Update an existing context blob.

**Parameters:**
- `blob_id`: ID of blob to update
- `updates`: Dictionary of fields to update

**Returns:**
- `True` if update successful
- `False` if blob not found or permission denied

**Example:**
```python
# Update blob content and tags
success = context_update(blob_id, {
    "content": "Updated documentation with new examples",
    "tags": ["auth", "security", "users", "examples"]
})
```

## Subscription API

### `context_subscribe(path: str, callback: Callable, filters: dict = None) -> str`

Subscribe to context changes at the specified path.

**Parameters:**
- `path`: Path to monitor
- `callback`: Function to call when changes occur
- `filters`: Optional filters for subscription

**Returns:**
- Subscription ID string

**Example:**
```python
def on_context_change(event):
    print(f"Context changed at {event.path}: {event.change_type}")

# Subscribe to changes in current directory
sub_id = context_subscribe(
    "/project/src/",
    callback=on_context_change,
    filters={"change_type": ["create", "update"]}
)
```

### `context_unsubscribe(subscription_id: str) -> bool`

Cancel a context subscription.

**Parameters:**
- `subscription_id`: ID returned from `context_subscribe`

**Returns:**
- `True` if unsubscribe successful
- `False` if subscription not found

**Example:**
```python
success = context_unsubscribe(sub_id)
```

## Data Models

### ContextBlob

```python
class ContextBlob:
    id: str                          # Unique blob identifier
    content: str                     # Main content text
    content_type: str               # Type: "code", "documentation", "config", etc.
    tags: List[str]                 # Searchable tags
    metadata: Dict[str, Any]        # Additional metadata
    author: str                     # Creator identifier
    created_at: datetime            # Creation timestamp
    updated_at: datetime            # Last update timestamp
    version: int                    # Version number
    parent_version: Optional[str]   # Parent blob ID if forked
```

### ContextPath

```python
class ContextPath:
    path: str                       # Full path string
    components: List[str]           # Path components
    depth: int                      # Depth from root
    is_absolute: bool               # True if absolute path
    exists: bool                    # True if path has context
```

### ContextQuery

```python
class ContextQuery:
    query: str                      # Search query
    filters: Dict[str, Any]         # Search filters
    scope: str                      # Search scope path
    limit: int                      # Max results
    offset: int                     # Results offset
    sort_by: str                    # Sort field
    sort_order: str                 # "asc" or "desc"
```

## Error Handling

All API functions raise specific exceptions for different error conditions:

- `PathNotFoundError`: Path does not exist
- `PermissionDeniedError`: Insufficient permissions
- `InvalidPathError`: Malformed path syntax
- `ContextNotFoundError`: Context blob not found
- `ValidationError`: Invalid data provided
- `StorageError`: Backend storage error

**Example:**
```python
from hcfs.api import PathNotFoundError, PermissionDeniedError

try:
    context = context_get(depth=2)
except PathNotFoundError:
    print("Current path has no context")
except PermissionDeniedError:
    print("Access denied to context")
```

## Configuration

API behavior can be configured via `HCFSConfig`:

```python
from hcfs.utils import HCFSConfig

config = HCFSConfig(
    max_depth=10,                   # Maximum traversal depth
    cache_size=1000,                # LRU cache size
    default_content_type="text",    # Default blob content type
    enable_versioning=True,         # Enable blob versioning
    subscription_timeout=300        # Subscription timeout (seconds)
)
```