API Reference

Experimental API - Context Engine SDK is experimental and subject to breaking changes.

DirectContext

This class provides explicit file indexing via API calls with the ability to import and export state to avoid re-indexing between sessions.

Examples

Example 1: Simple Usage

Upload files and ask questions immediately:

import { DirectContext } from '@augmentcode/auggie-sdk';

async function simpleExample() {
  // Create context (authentication is automatic)
  const context = await DirectContext.create();

  // Add files and wait for indexing (default behavior)
  const result = await context.addToIndex([
    { path: 'src/auth.ts', contents: 'export function login(user, pass) { ... }' },
    { path: 'src/user.ts', contents: 'export class User { constructor(id) { ... } }' },
    { path: 'README.md', contents: '# My Project\nAuthentication system' }
  ]);

  console.log(`Newly uploaded: ${result.newlyUploaded.length}`);

  // Ask questions about the code - files are already indexed
  const answer = await context.searchAndAsk(
    'How does the login system work?'
  );
  console.log('Answer:', answer);
}

simpleExample().catch(console.error);

from auggie_sdk.context import DirectContext, File

def simple_example():
    # Create context (authentication is automatic)
    context = DirectContext.create()

    # Add files and wait for indexing (default behavior)
    result = context.add_to_index([
        File(path='src/auth.py', contents='def login(user, password): ...'),
        File(path='src/user.py', contents='class User:\n    def __init__(self, id): ...'),
        File(path='README.md', contents='# My Project\nAuthentication system')
    ])

    print(f"Newly uploaded: {len(result.newly_uploaded)}")

    # Ask questions about the code - files are already indexed
    answer = context.search_and_ask(
        'How does the login system work?'
    )
    print('Answer:', answer)

if __name__ == '__main__':
    simple_example()

Example 2: Persistent Index

Persist state between sessions to avoid re-indexing. This is useful when you want to save the index state to disk and reload it later without having to re-upload and re-index all files. The saved state file contains metadata about which files are indexed, allowing you to resume from where you left off:

import { DirectContext } from '@augmentcode/auggie-sdk';

// First session: Upload and save
async function uploadAndSave() {
  const context = await DirectContext.create();

  // Upload files
  await context.addToIndex([
    { path: 'src/auth.ts', contents: 'export function login() { ... }' },
    { path: 'src/user.ts', contents: 'export class User { ... }' },
    { path: 'src/database.ts', contents: 'export function connect() { ... }' }
  ]);

  // Save state for later use - this creates a JSON file containing the index metadata
  // so you can reload it later without re-indexing all files
  await context.exportToFile('./my-project-context.json');
  console.log('Context saved!');
  console.log('You can now reload this state in a future session using importFromFile()');
}

// Second session: Load, update incrementally, and save again
async function updateAndSave() {
  // Load previous state - this restores the index without re-uploading files
  const context = await DirectContext.importFromFile('./my-project-context.json');
  console.log('Context loaded from previous session - no re-indexing needed!');

  // Make incremental changes - remove old file and add new one
  await context.removeFromIndex(['src/user.ts']);
  await context.addToIndex([
    { path: 'src/profile.ts', contents: 'export class Profile { /* profile logic */ }' },
    { path: 'src/settings.ts', contents: 'export function updateSettings() { /* settings */ }' }
  ]);
  console.log('Index updated incrementally');

  // Save updated state
  await context.exportToFile('./my-project-context.json');
  console.log('Updated context saved!');
}

// Third session: Load and search
async function loadAndSearch() {
  // Load the updated state
  const context = await DirectContext.importFromFile('./my-project-context.json');
  console.log('Updated context loaded');

  // Search immediately - files are already indexed
  const answer = await context.searchAndAsk(
    'What user management features are implemented?'
  );
  console.log('Answer:', answer);
}

// Run the complete workflow: upload → update → search
uploadAndSave()
  .then(() => updateAndSave())
  .then(() => loadAndSearch())
  .catch(console.error);

from auggie_sdk.context import DirectContext, File

# First session: Upload and save
def upload_and_save():
    context = DirectContext.create()

    # Upload files
    context.add_to_index([
        File(path='src/auth.py', contents='def login(): ...'),
        File(path='src/user.py', contents='class User: ...'),
        File(path='src/database.py', contents='def connect(): ...')
    ])

    # Save state for later use - this creates a JSON file containing the index metadata
    # so you can reload it later without re-indexing all files
    context.export_to_file('./my-project-context.json')
    print('Context saved!')
    print('You can now reload this state in a future session using import_from_file()')

# Second session: Load, update incrementally, and save again
def update_and_save():
    # Load previous state - this restores the index without re-uploading files
    context = DirectContext.import_from_file('./my-project-context.json')
    print('Context loaded from previous session - no re-indexing needed!')

    # Make incremental changes - remove old file and add new one
    context.remove_from_index(['src/user.py'])
    context.add_to_index([
        File(path='src/profile.py', contents='class Profile: # profile logic'),
        File(path='src/settings.py', contents='def update_settings(): # settings')
    ])
    print('Index updated incrementally')

    # Save updated state
    context.export_to_file('./my-project-context.json')
    print('Updated context saved!')

# Third session: Load and search
def load_and_search():
    # Load the updated state
    context = DirectContext.import_from_file('./my-project-context.json')
    print('Updated context loaded')

    # Search immediately - files are already indexed
    answer = context.search_and_ask(
        'What user management features are implemented?'
    )
    print('Answer:', answer)

# Run the complete workflow: upload → update → search
if __name__ == '__main__':
    upload_and_save()
    update_and_save()
    load_and_search()

Example 3: Batch Upload Then Wait

When you need to upload many files in multiple batches, you can optimize performance by uploading all files first without waiting for indexing, then waiting once at the end. This approach is faster than waiting for indexing after each batch:

import { DirectContext } from '@augmentcode/auggie-sdk';

async function batchExample() {
  const context = await DirectContext.create();

  // Upload multiple batches without waiting for indexing
  await context.addToIndex([
    { path: 'src/auth.ts', contents: 'export function login() { ... }' },
    { path: 'src/user.ts', contents: 'export class User { ... }' }
  ], { waitForIndexing: false });

  await context.addToIndex([
    { path: 'src/database.ts', contents: 'export function connect() { ... }' },
    { path: 'src/api.ts', contents: 'export function createServer() { ... }' }
  ], { waitForIndexing: false });

  // Wait for all files to be indexed
  console.log('Waiting for indexing to complete...');
  await context.waitForIndexing();
  console.log('All files indexed!');

  // Now search - all files are guaranteed to be indexed
  const answer = await context.searchAndAsk(
    'How do the database and auth systems work together?'
  );
  console.log('Answer:', answer);
}

batchExample().catch(console.error);

from auggie_sdk.context import DirectContext, File

def batch_example():
    context = DirectContext.create()

    # Upload multiple batches without waiting for indexing
    context.add_to_index([
        File(path='src/auth.py', contents='def login(): ...'),
        File(path='src/user.py', contents='class User: ...')
    ], wait_for_indexing=False)

    context.add_to_index([
        File(path='src/database.py', contents='def connect(): ...'),
        File(path='src/api.py', contents='def create_server(): ...')
    ], wait_for_indexing=False)

    # Wait for all files to be indexed
    print('Waiting for indexing to complete...')
    context.wait_for_indexing()
    print('All files indexed!')

    # Now search - all files are guaranteed to be indexed
    answer = context.search_and_ask(
        'How do the database and auth systems work together?'
    )
    print('Answer:', answer)

if __name__ == '__main__':
    batch_example()

Example 4: Custom Prompts

Use searchAndAsk with custom prompts for diverse tasks:

import { DirectContext } from '@augmentcode/auggie-sdk';

async function creativeExample() {
  const context = await DirectContext.create();

  // Upload some code
  await context.addToIndex([
    { path: 'src/auth.ts', contents: 'export function login(user, pass) { /* auth logic */ }' },
    { path: 'src/database.ts', contents: 'export function connect() { /* db connection */ }' },
    { path: 'README.md', contents: '# My App\nA secure authentication system' }
  ]);

  // Creative prompts with searchAndAsk
  const poem = await context.searchAndAsk(
    'authentication system',
    'Write a haiku about this authentication code'
  );
  console.log('Haiku:', poem);

  // Generate documentation
  const docs = await context.searchAndAsk(
    'database authentication flow',
    'Write a brief user guide explaining how to use the database authentication flow'
  );
  console.log('Documentation:', docs);

  // Code review style analysis
  const review = await context.searchAndAsk(
    'authentication logic',
    'Provide a code review focusing on security best practices'
  );
  console.log('Code Review:', review);
}

creativeExample().catch(console.error);

from auggie_sdk.context import DirectContext, File

def creative_example():
    context = DirectContext.create()

    # Upload some code
    context.add_to_index([
        File(path='src/auth.py', contents='def login(user, password): # auth logic'),
        File(path='src/database.py', contents='def connect(): # db connection'),
        File(path='README.md', contents='# My App\nA secure authentication system')
    ])

    # Creative prompts with search_and_ask
    poem = context.search_and_ask(
        'authentication system',
        'Write a haiku about this authentication code'
    )
    print('Haiku:', poem)

    # Generate documentation
    docs = context.search_and_ask(
        'database authentication flow',
        'Write a brief user guide explaining how to use the database authentication flow'
    )
    print('Documentation:', docs)

    # Code review style analysis
    review = context.search_and_ask(
        'authentication logic',
        'Provide a code review focusing on security best practices'
    )
    print('Code Review:', review)

if __name__ == '__main__':
    creative_example()

Example 5: External LLM Integration

Use search() results with external LLM APIs:

import { DirectContext } from '@augmentcode/auggie-sdk';
// import { Anthropic } from '@anthropic-ai/sdk';
// import OpenAI from 'openai';

async function externalLLMExample() {
  const context = await DirectContext.create();

  // Upload code
  await context.addToIndex([
    { path: 'src/api.ts', contents: 'export function handleRequest() { /* API logic */ }' },
    { path: 'src/auth.ts', contents: 'export function authenticate() { /* auth */ }' },
    { path: 'src/database.ts', contents: 'export function query() { /* db query */ }' }
  ]);

  // Get formatted search results for external LLMs
  const codeContext = await context.search('API request handling');

  // codeContext is a formatted string ready to embed in prompts for
  // Anthropic, OpenAI, or other LLM APIs
  console.log('Code context for LLM:', codeContext);

  // Example: Use with Anthropic Claude (uncomment to use)
  // const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
  // const response = await anthropic.messages.create({
  //   model: 'claude-sonnet-4-5-20250929',
  //   max_tokens: 1000,
  //   messages: [{
  //     role: 'user',
  //     content: `Based on this code:\n\n${codeContext}\n\nHow can I improve the error handling in the API?`
  //   }]
  // });
  // console.log('Claude response:', response.content[0].text);

  // Example: Use with OpenAI GPT-5.1 (uncomment to use)
  // const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
  // const completion = await openai.chat.completions.create({
  //   model: 'gpt-5.1',
  //   messages: [{
  //     role: 'user',
  //     content: `Based on this code:\n\n${codeContext}\n\nSuggest performance optimizations for this API.`
  //   }]
  // });
  // console.log('GPT-5.1 response:', completion.choices[0].message.content);


}

externalLLMExample().catch(console.error);

from auggie_sdk.context import DirectContext, File
# import anthropic
# import openai

def external_llm_example():
    context = DirectContext.create()

    # Upload code
    context.add_to_index([
        File(path='src/api.py', contents='def handle_request(): # API logic'),
        File(path='src/auth.py', contents='def authenticate(): # auth'),
        File(path='src/database.py', contents='def query(): # db query')
    ])

    # Get formatted search results for external LLMs
    code_context = context.search('API request handling')

    # code_context is a formatted string ready to embed in prompts for
    # Anthropic, OpenAI, or other LLM APIs
    print('Code context for LLM:', code_context)

    # Example: Use with Anthropic Claude (uncomment to use)
    # client = anthropic.Anthropic(api_key=os.environ['ANTHROPIC_API_KEY'])
    # response = client.messages.create(
    #     model='claude-sonnet-4-5-20250929',
    #     max_tokens=1000,
    #     messages=[{
    #         'role': 'user',
    #         'content': f'Based on this code:\n\n{code_context}\n\nHow can I improve the error handling?'
    #     }]
    # )
    # print('Claude response:', response.content[0].text)

    # Example: Use with OpenAI GPT-5.1 (uncomment to use)
    # client = openai.OpenAI(api_key=os.environ['OPENAI_API_KEY'])
    # completion = client.chat.completions.create(
    #     model='gpt-5.1',
    #     messages=[{
    #         'role': 'user',
    #         'content': f'Based on this code:\n\n{code_context}\n\nSuggest performance optimizations.'
    #     }]
    # )
    # print('GPT-5.1 response:', completion.choices[0].message.content)

if __name__ == '__main__':
    external_llm_example()

DirectContext.create()

Create and initialize a new DirectContext instance.

static async create(options?: DirectContextOptions): Promise<DirectContext>

interface DirectContextOptions {
  apiKey?: string;      // Optional - falls back to env vars or session.json
  apiUrl?: string;      // Optional - falls back to env vars or session.json
  debug?: boolean;      // Enable debug logging (default: false)
}

@classmethod
def create(
    cls,
    *,
    api_key: Optional[str] = None,
    api_url: Optional[str] = None,
    debug: bool = False,
) -> DirectContext

Parameters:

options - Optional configuration object
- apiKey - API key for authentication (optional)
- apiUrl - API URL for your tenant (optional)
- debug - Enable debug logging (optional, default: false)

Authentication Priority:

options.apiKey / options.apiUrl (passed to create())
AUGMENT_SESSION_AUTH environment variable (session JSON from auggie token print)
~/.augment/session.json (created by auggie login)

Usage: See complete examples above for full implementation details. Notes:

The SDK is source-agnostic - you provide files as {path, contents} objects
Files larger than 1MB are rejected during indexing
All indexing operations are serialized to ensure consistency
State can be saved and loaded to avoid re-indexing

DirectContext.importFromFile() / import_from_file()

Create a DirectContext instance from a saved state file.

static async importFromFile(
  filePath: string,
  options?: DirectContextOptions
): Promise<DirectContext>

@classmethod
def import_from_file(
    cls,
    file_path: str,
    *,
    api_key: Optional[str] = None,
    api_url: Optional[str] = None,
    debug: bool = False,
) -> DirectContext

Parameters:

filePath / file_path - Path to the saved state file
options - Optional configuration object (same as create())

Returns: A DirectContext instance with restored state Usage:

// Load context from saved state
const context = await DirectContext.importFromFile('./my-context.json');
// Files are already indexed, ready to search

# Load context from saved state
context = DirectContext.import_from_file('./my-context.json')
# Files are already indexed, ready to search

DirectContext.import() / import_state()

Create a DirectContext instance from a saved state object.

static async import(
  state: DirectContextState,
  options?: DirectContextOptions
): Promise<DirectContext>

@classmethod
def import_state(
    cls,
    state: DirectContextState,
    *,
    api_key: Optional[str] = None,
    api_url: Optional[str] = None,
    debug: bool = False,
) -> DirectContext

Parameters:

state - The state object to restore from
options - Optional configuration object (same as create())

Returns: A DirectContext instance with restored state Usage:

// Load context from state object
const savedState = JSON.parse(stateJson);
const context = await DirectContext.import(savedState);

import json
# Load context from state object
with open('state.json') as f:
    saved_state = DirectContextState.from_dict(json.load(f))
context = DirectContext.import_state(saved_state)

DirectContext Methods

addToIndex() / add_to_index()

Add files to the index. Files can come from any source - memory, disk, API, database, etc.

async addToIndex(
  files: File[],
  options?: { waitForIndexing?: boolean }
): Promise<IndexingResult>

interface File {
  path: string;      // Relative path (e.g., "src/main.ts")
  contents: string;  // File contents as string
}

interface IndexingResult {
  newlyUploaded: string[];     // Paths that were uploaded and indexed
  alreadyUploaded: string[];   // Paths that were skipped (already on server)
}

def add_to_index(
    self,
    files: List[File],
    wait_for_indexing: bool = True
) -> IndexingResult

@dataclass
class File:
    path: str       # Relative path (e.g., "src/main.py")
    contents: str   # File contents as string

@dataclass
class IndexingResult:
    newly_uploaded: List[str]     # Paths that were uploaded and indexed
    already_uploaded: List[str]   # Paths that were skipped (already on server)

Parameters:

files - Array/list of file objects with path and contents
options / wait_for_indexing - Optional configuration
- waitForIndexing / wait_for_indexing - If true (default), waits for the newly added files to be indexed before returning

Returns: IndexingResult object with details about what was indexed Notes:

Files larger than 1MB will throw an error
By default, waits for backend indexing to complete before returning (set waitForIndexing: false / wait_for_indexing=False to return immediately after upload)
If a file with the same path already exists, it will be updated
All operations are serialized to ensure consistency
The SDK optimizes uploads by checking which blobs the server already has and only uploading missing ones

removeFromIndex() / remove_from_index()

Remove files from the index by path.

async removeFromIndex(paths: string[]): Promise<void>

def remove_from_index(self, paths: List[str]) -> None

Parameters:

paths - Array/list of file paths to remove

clearIndex() / clear_index()

Clear the entire index, removing all files.

async clearIndex(): Promise<void>

def clear_index(self) -> None

getIndexedPaths() / get_indexed_paths()

Get the list of currently indexed file paths.

getIndexedPaths(): string[]

def get_indexed_paths(self) -> List[str]

Returns: Array/list of relative file paths that are currently indexed Use Cases:

Display indexed files to users
Verify which files are included in the index
Filter files for targeted searches

search()

Search the codebase and return formatted results as a string.

async search(
  query: string,
  options?: { maxOutputLength?: number }
): Promise<string>

def search(
    self,
    query: str,
    max_output_length: Optional[int] = None
) -> str

Parameters:

query - Natural language search query
options / max_output_length - Optional search options
- maxOutputLength / max_output_length - Maximum character length of the formatted output (default: 20000, max: 80000)

Returns: Formatted string containing the search results, ready for LLM consumption Notes:

Returns a formatted string designed for use in LLM prompts
The format includes file paths, line numbers, and code content
Does NOT wait for indexing - ensure files are indexed before searching by either:
- Using addToIndex() / add_to_index() with waitForIndexing: true / wait_for_indexing=True (default)
- Calling waitForIndexing() / wait_for_indexing() explicitly before searching
Throws an error if the index is empty

searchAndAsk() / search_and_ask()

Search the indexed codebase and ask an LLM a question about the results. This is a convenience method that combines search() with an LLM call to answer questions about your codebase.

async searchAndAsk(
  searchQuery: string,
  prompt?: string
): Promise<string>

def search_and_ask(
    self,
    search_query: str,
    prompt: Optional[str] = None
) -> str

Parameters:

searchQuery / search_query - The semantic search query to find relevant code (also used as the prompt if no separate prompt is provided)
prompt - Optional prompt to ask the LLM about the search results. If not provided, searchQuery is used as the prompt.

Returns: The LLM’s answer to your question Notes:

Does NOT wait for indexing - ensure files are indexed before searching by either:
- Using addToIndex() / add_to_index() with waitForIndexing: true / wait_for_indexing=True (default)
- Calling waitForIndexing() / wait_for_indexing() explicitly before searching
Requires authentication via auggie login, AUGMENT_SESSION_AUTH environment variable, or API credentials for LLM access

Use Cases:

Quick Q&A about your codebase
Building conversational interfaces
Automated code analysis and documentation

waitForIndexing() / wait_for_indexing()

Wait for all indexed files to be fully indexed on the backend. This method polls the backend until all files that have been added to the index are confirmed to be indexed and searchable.

async waitForIndexing(): Promise<void>

def wait_for_indexing(self) -> None

Returns: Promise that resolves when all files are indexed Notes:

Throws an error if indexing times out (default: 10 minutes)
Only waits for files that have been added to the index
Useful when you want to control when to wait for indexing completion

Use Cases:

Batch upload multiple files quickly, then wait for all to be indexed
Ensure search results include all recently added files
Control timing of indexing waits in complex workflows

exportToFile() / export_to_file()

Export the current state to a file.

async exportToFile(filePath: string): Promise<void>

def export_to_file(self, file_path: str) -> None

Parameters:

filePath / file_path - Path to save the state file

Use Cases:

Persist indexing state between sessions
Avoid re-indexing large codebases
Share indexing state across different processes

export()

Export the current state as an object (in-memory).

export(): DirectContextState

interface DirectContextState {
  checkpointId?: string;
  addedBlobs: string[];
  deletedBlobs: string[];
  blobs: BlobEntry[];  // Array of [blobName, path] tuples
}

def export(self) -> DirectContextState

@dataclass
class DirectContextState:
    checkpoint_id: Optional[str]
    added_blobs: List[str]
    deleted_blobs: List[str]
    blobs: List[Tuple[str, str]]  # List of (blob_name, path) tuples

Returns: State object that can be serialized and stored

FileSystemContext

This class provides automatic indexing and search capabilities for a local directory.

FileSystemContext.create()

Create and initialize a new FileSystemContext instance.

static async create(options: FileSystemContextOptions): Promise<FileSystemContext>

interface FileSystemContextOptions {
  directory: string;      // Path to the workspace directory to index
  auggiePath?: string;    // Path to auggie executable (default: "auggie")
  debug?: boolean;        // Enable debug logging (default: false)
}

@classmethod
def create(
    cls,
    directory: str,
    *,
    auggie_path: str = "auggie",
    debug: bool = False,
) -> FileSystemContext

Parameters:

options / positional args - Configuration
- directory - Path to the workspace directory to index (required)
- auggiePath / auggie_path - Path to auggie executable (optional, default: “auggie”)
- debug - Enable debug logging (optional, default: false)

Usage: See DirectContext examples above for similar patterns. Notes:

Automatically indexes the directory on startup
Requires auggie CLI to be installed and accessible
Python supports context manager (with statement) for automatic cleanup

FileSystemContext Methods

search()

Search the codebase and return formatted results as a string.

async search(query: string): Promise<string>

def search(self, query: str) -> str

Parameters:

query - Natural language search query

Returns: Formatted string containing the search results, ready for LLM consumption

searchAndAsk() / search_and_ask()

Search the indexed codebase and ask an LLM a question about the results.

async searchAndAsk(
  searchQuery: string,
  prompt?: string
): Promise<string>

def search_and_ask(
    self,
    search_query: str,
    prompt: Optional[str] = None
) -> str

Parameters:

searchQuery / search_query - The semantic search query to find relevant code (also used as the prompt if no separate prompt is provided)
prompt - Optional prompt to ask the LLM about the search results. If not provided, searchQuery is used as the prompt.

Returns: The LLM’s answer to your question Notes:

Requires authentication via auggie login, AUGMENT_SESSION_AUTH environment variable, or API credentials for LLM access

close()

Close the connection and cleanup resources.

async close(): Promise<void>

def close(self) -> None

Notes:

Always call close() when done to cleanup resources
Python: Use context manager (with statement) for automatic cleanup

Types

File

Represents a file to be indexed (input type for addToIndex() / add_to_index()).

interface File {
  path: string;      // Relative path (e.g., "src/main.ts")
  contents: string;  // File contents as string
}

@dataclass
class File:
    path: str       # Relative path (e.g., "src/main.py")
    contents: str   # File contents as string

IndexingResult

Result from addToIndex() / add_to_index() operation showing what was indexed.

interface IndexingResult {
  newlyUploaded: string[];     // Paths that were uploaded and indexed
  alreadyUploaded: string[];   // Paths that were skipped (already on server)
}

@dataclass
class IndexingResult:
    newly_uploaded: List[str]     # Paths that were uploaded and indexed
    already_uploaded: List[str]   # Paths that were skipped (already on server)

Notes:

newlyUploaded / newly_uploaded: Files that were uploaded to the server and indexed
alreadyUploaded / already_uploaded: Files that were skipped because:
- They were already in the local cache with the same content, OR
- The server already had the blob (detected via find-missing API)

DirectContextOptions (TypeScript) / Keyword Arguments (Python)

Options for configuring DirectContext.

interface DirectContextOptions {
  apiKey?: string;      // API key for authentication
  apiUrl?: string;      // API URL for your Augment tenant
  debug?: boolean;      // Enable debug logging (default: false)
}

# In Python, these are passed as keyword arguments to create():
DirectContext.create(
    api_key: Optional[str] = None,  # API key for authentication
    api_url: Optional[str] = None,  # API URL for your Augment tenant
    debug: bool = False,            # Enable debug logging (default: False)
)

DirectContextState

State for DirectContext that can be saved/loaded.

interface DirectContextState {
  checkpointId?: string;      // Current checkpoint ID
  addedBlobs: string[];       // Blob names added (pending checkpoint)
  deletedBlobs: string[];     // Blob names deleted (pending checkpoint)
  blobs: BlobEntry[];         // List of blobs as [blobName, path] tuples
}

type BlobEntry = [blobName: string, path: string];

@dataclass
class DirectContextState:
    checkpoint_id: Optional[str]       # Current checkpoint ID
    added_blobs: List[str]             # Blob names added (pending checkpoint)
    deleted_blobs: List[str]           # Blob names deleted (pending checkpoint)
    blobs: List[Tuple[str, str]]       # List of (blob_name, path) tuples

    def to_dict(self) -> Dict[str, Any]:
        """Convert to JSON-serializable dict."""
        ...

    @classmethod
    def from_dict(cls, data: Dict[str, Any]) -> DirectContextState:
        """Create from JSON dict (e.g., from imported state file)."""
        ...

Serialization Example:

// DirectContextState is a plain object, use JSON.parse/stringify
const stateJson = JSON.stringify(context.export());
const restoredState = JSON.parse(stateJson);
const newContext = await DirectContext.import(restoredState);

import json

# Export state and serialize to JSON
state = context.export()
state_json = json.dumps(state.to_dict())

# Later: deserialize and import
data = json.loads(state_json)
restored_state = DirectContextState.from_dict(data)
new_context = DirectContext.import_state(restored_state)

FileSystemContextOptions (TypeScript) / Keyword Arguments (Python)

Options for FileSystem Context.

interface FileSystemContextOptions {
  directory: string;      // Path to the workspace directory to index
  auggiePath?: string;    // Path to auggie executable (default: "auggie")
  debug?: boolean;        // Enable debug logging (default: false)
}

# In Python, these are passed as arguments to create():
FileSystemContext.create(
    directory: str,                    # Path to the workspace directory to index
    auggie_path: str = "auggie",       # Path to auggie executable (default: "auggie")
    debug: bool = False,               # Enable debug logging (default: False)
)

Authentication

The SDK automatically loads credentials from multiple sources in this priority order:

Options/keyword arguments: apiKey/api_key and apiUrl/api_url passed to DirectContext.create()
Environment variable: AUGMENT_SESSION_AUTH (session JSON from auggie token print)
Session file: ~/.augment/session.json (created by auggie login)

To get credentials:

Sign in to Augment using the CLI: auggie login
Your credentials will be stored in ~/.augment/session.json
The SDK will automatically use them

Error Handling

The SDK exports specific error classes for better error handling:

Error Class	Description
`BlobTooLargeError`	File exceeds 1MB limit. Includes `path` and `size` properties.
`APIError`	Network or API request failures. Includes `status` property.

import { DirectContext, APIError, BlobTooLargeError } from '@augmentcode/auggie-sdk';

try {
  const context = await DirectContext.create();
  await context.addToIndex([
    { path: 'test.ts', contents: '...' }
  ]);
  const results = await context.search('query');
} catch (error) {
  if (error instanceof BlobTooLargeError) {
    console.error('File too large (max 1MB):', error.path);
  } else if (error instanceof APIError) {
    console.error('API request failed:', error.message);
    console.error('Status code:', error.status);
  } else if (error.message.includes('API key is required')) {
    console.error('Missing credentials');
  } else if (error.message.includes('Index not initialized')) {
    console.error('No files indexed yet');
  } else {
    console.error('Operation failed:', error);
  }
}

from auggie_sdk.context import DirectContext, File, APIError, BlobTooLargeError

try:
    context = DirectContext.create()
    context.add_to_index([
        File(path='test.py', contents='...')
    ])
    results = context.search('query')
except BlobTooLargeError as error:
    print('File too large (max 1MB):', error)
except APIError as error:
    print('API request failed:', error)
except ValueError as error:
    if 'API key is required' in str(error):
        print('Missing credentials')
    elif 'Index not initialized' in str(error):
        print('No files indexed yet')
    else:
        print('Operation failed:', error)
except Exception as error:
    print('Operation failed:', error)

​DirectContext

​Examples

​Example 1: Simple Usage

​Example 2: Persistent Index

​Example 3: Batch Upload Then Wait

​Example 4: Custom Prompts

​Example 5: External LLM Integration

​API Reference

​DirectContext.create()

​DirectContext.importFromFile() / import_from_file()

​DirectContext.import() / import_state()

​DirectContext Methods

​addToIndex() / add_to_index()

​removeFromIndex() / remove_from_index()

​clearIndex() / clear_index()

​getIndexedPaths() / get_indexed_paths()

​search()

​searchAndAsk() / search_and_ask()

​waitForIndexing() / wait_for_indexing()

​exportToFile() / export_to_file()

​export()

​FileSystemContext

​FileSystemContext.create()

​FileSystemContext Methods

​search()

​searchAndAsk() / search_and_ask()

​close()

​Types

​File

​IndexingResult

​DirectContextOptions (TypeScript) / Keyword Arguments (Python)

​DirectContextState

​FileSystemContextOptions (TypeScript) / Keyword Arguments (Python)

​Authentication

​Error Handling

DirectContext

Examples

Example 1: Simple Usage

Example 2: Persistent Index

Example 3: Batch Upload Then Wait

Example 4: Custom Prompts

Example 5: External LLM Integration

API Reference

DirectContext.create()

DirectContext.importFromFile() / import_from_file()

DirectContext.import() / import_state()

DirectContext Methods

addToIndex() / add_to_index()

removeFromIndex() / remove_from_index()

clearIndex() / clear_index()

getIndexedPaths() / get_indexed_paths()

search()

searchAndAsk() / search_and_ask()

waitForIndexing() / wait_for_indexing()

exportToFile() / export_to_file()

export()

FileSystemContext

FileSystemContext.create()

FileSystemContext Methods

search()

searchAndAsk() / search_and_ask()

close()

Types

File

IndexingResult

DirectContextOptions (TypeScript) / Keyword Arguments (Python)

DirectContextState

FileSystemContextOptions (TypeScript) / Keyword Arguments (Python)

Authentication

Error Handling