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:

# 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:

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:

# 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:

# 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:

# 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:

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:

# 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:

# 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:

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:

success = context_unsubscribe(sub_id)

Data Models

ContextBlob

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

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

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:

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:

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)
)