MicroDC Client - Basic Usage¶

This notebook demonstrates the basic usage of the MicroDC client library for submitting inference jobs to the MicroDC.ai distributed inference platform.

Prerequisites¶

# Install from GitLab repository (v1 branch)
pip install git+https://gitlab.com/microdc/python-client.git@v1

You'll also need a MicroDC API key. Set it as an environment variable:

export MICRODC_API_KEY=mDC_YOUR-API-KEY-HERE

1. Basic LLM Call¶

In [ ]:

from microDC import Client, LLMCall

# Initialize the client (uses MICRODC_API_KEY from environment)
client = Client()

# Create a simple LLM job
job = LLMCall(model="llama3.3")
job.add_user_message("Why is the sky blue? Explain in simple terms.")

# Send the job and wait for results
job_id = client.send_job(job)
print(f"Job submitted: {job_id}")

# Wait for completion
client.wait_for_all()

# Get the result
result = client.get_job_details(job_id)
if result.is_successful():
    print("\nResponse:")
    print(result.result)
else:
    print(f"Error: {result.error_message}")

from microDC import Client, LLMCall # Initialize the client (uses MICRODC_API_KEY from environment) client = Client() # Create a simple LLM job job = LLMCall(model="llama3.3") job.add_user_message("Why is the sky blue? Explain in simple terms.") # Send the job and wait for results job_id = client.send_job(job) print(f"Job submitted: {job_id}") # Wait for completion client.wait_for_all() # Get the result result = client.get_job_details(job_id) if result.is_successful(): print("\nResponse:") print(result.result) else: print(f"Error: {result.error_message}")

2. Using Callbacks for Async Processing¶

In [ ]:

from microDC import Client, LLMCall


# Define a callback function
def handle_completion(client: Client, job_id: str):
    details = client.get_job_details(job_id)
    print(f"\n{'=' * 50}")
    print(f"Job {job_id[:8]}... completed!")
    if details.is_successful():
        print(f"Result: {details.result[:100]}...")
    else:
        print(f"Error: {details.error_message}")
    print(f"{'=' * 50}\n")


# Create client with callback
client = Client()
client.set_callback(handle_completion)

# Submit multiple jobs
questions = [
    "What is machine learning?",
    "Explain distributed computing.",
    "What are neural networks?",
]

job_ids = []
for question in questions:
    job = LLMCall(model="llama3.3", max_tokens=150)
    job.add_user_message(question)
    job_id = client.send_job(job)
    job_ids.append(job_id)
    print(f"Submitted: {question}")

# Wait for all jobs to complete (callbacks will be invoked automatically)
print("\nWaiting for all jobs to complete...")
client.wait_for_all()
print("All jobs completed!")

from microDC import Client, LLMCall # Define a callback function def handle_completion(client: Client, job_id: str): details = client.get_job_details(job_id) print(f"\n{'=' * 50}") print(f"Job {job_id[:8]}... completed!") if details.is_successful(): print(f"Result: {details.result[:100]}...") else: print(f"Error: {details.error_message}") print(f"{'=' * 50}\n") # Create client with callback client = Client() client.set_callback(handle_completion) # Submit multiple jobs questions = [ "What is machine learning?", "Explain distributed computing.", "What are neural networks?", ] job_ids = [] for question in questions: job = LLMCall(model="llama3.3", max_tokens=150) job.add_user_message(question) job_id = client.send_job(job) job_ids.append(job_id) print(f"Submitted: {question}") # Wait for all jobs to complete (callbacks will be invoked automatically) print("\nWaiting for all jobs to complete...") client.wait_for_all() print("All jobs completed!")

3. Embedding Generation¶

In [ ]:

import numpy as np

from microDC import Client, EmbedCall

client = Client()

# Create embedding job
texts = [
    "The quick brown fox jumps over the lazy dog.",
    "A fast auburn fox leaps over a sleepy canine.",
    "Python is a popular programming language.",
]

job = EmbedCall(model="text-embedding-3-small")
for text in texts:
    job.add_text(text)

# Submit and wait
job_id = client.send_job(job)
client.wait_for_all()

# Get embeddings
result = client.get_job_details(job_id)
if result.is_successful():
    embeddings = result.result  # List of embedding vectors
    print(f"Generated {len(embeddings)} embeddings")
    print(f"Embedding dimension: {len(embeddings[0])}")

    # Calculate similarity between first two texts
    vec1 = np.array(embeddings[0])
    vec2 = np.array(embeddings[1])
    vec3 = np.array(embeddings[2])

    similarity_1_2 = np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2))
    similarity_1_3 = np.dot(vec1, vec3) / (np.linalg.norm(vec1) * np.linalg.norm(vec3))

    print(f"\nSimilarity between text 1 and 2 (similar): {similarity_1_2:.4f}")
    print(f"Similarity between text 1 and 3 (different): {similarity_1_3:.4f}")
else:
    print(f"Error: {result.error_message}")

import numpy as np from microDC import Client, EmbedCall client = Client() # Create embedding job texts = [ "The quick brown fox jumps over the lazy dog.", "A fast auburn fox leaps over a sleepy canine.", "Python is a popular programming language.", ] job = EmbedCall(model="text-embedding-3-small") for text in texts: job.add_text(text) # Submit and wait job_id = client.send_job(job) client.wait_for_all() # Get embeddings result = client.get_job_details(job_id) if result.is_successful(): embeddings = result.result # List of embedding vectors print(f"Generated {len(embeddings)} embeddings") print(f"Embedding dimension: {len(embeddings[0])}") # Calculate similarity between first two texts vec1 = np.array(embeddings[0]) vec2 = np.array(embeddings[1]) vec3 = np.array(embeddings[2]) similarity_1_2 = np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2)) similarity_1_3 = np.dot(vec1, vec3) / (np.linalg.norm(vec1) * np.linalg.norm(vec3)) print(f"\nSimilarity between text 1 and 2 (similar): {similarity_1_2:.4f}") print(f"Similarity between text 1 and 3 (different): {similarity_1_3:.4f}") else: print(f"Error: {result.error_message}")

4. Multi-turn Conversations¶

In [ ]:

from microDC import Client, LLMCall

client = Client()

# Create a conversation
job = LLMCall(model="llama3.3", temperature=0.7)
job.set_system_message("You are a helpful AI assistant specializing in Python programming.")
job.add_user_message("What is a list comprehension in Python?")

# First turn
job_id = client.send_job(job)
client.wait_for_all()
result = client.get_job_details(job_id)
print("Assistant:", result.result)

# Continue the conversation
job.add_assistant_message(result.result)
job.add_user_message("Can you show me an example with filtering?")

# Second turn
job_id = client.send_job(job)
client.wait_for_all()
result = client.get_job_details(job_id)
print("\nAssistant:", result.result)

from microDC import Client, LLMCall client = Client() # Create a conversation job = LLMCall(model="llama3.3", temperature=0.7) job.set_system_message("You are a helpful AI assistant specializing in Python programming.") job.add_user_message("What is a list comprehension in Python?") # First turn job_id = client.send_job(job) client.wait_for_all() result = client.get_job_details(job_id) print("Assistant:", result.result) # Continue the conversation job.add_assistant_message(result.result) job.add_user_message("Can you show me an example with filtering?") # Second turn job_id = client.send_job(job) client.wait_for_all() result = client.get_job_details(job_id) print("\nAssistant:", result.result)

5. Job Management¶

In [ ]:

from microDC import Client, LLMCall

client = Client()

# Submit a job
job = LLMCall(model="llama3.3")
job.add_user_message("Count from 1 to 100.")
job_id = client.send_job(job)

# Check status
status = client.get_job_status(job_id)
print(f"Job status: {status}")

# List all jobs
jobs = client.list_jobs()
print(f"\nTotal jobs: {len(jobs)}")
for job_info in jobs[:5]:  # Show first 5
    print(f"  {job_info['job_id'][:8]}... - {job_info['status']}")

# Cancel the job (if still running)
if status in ["queued", "running"]:
    client.cancel_job(job_id)
    print(f"\nCancelled job {job_id[:8]}...")

from microDC import Client, LLMCall client = Client() # Submit a job job = LLMCall(model="llama3.3") job.add_user_message("Count from 1 to 100.") job_id = client.send_job(job) # Check status status = client.get_job_status(job_id) print(f"Job status: {status}") # List all jobs jobs = client.list_jobs() print(f"\nTotal jobs: {len(jobs)}") for job_info in jobs[:5]: # Show first 5 print(f" {job_info['job_id'][:8]}... - {job_info['status']}") # Cancel the job (if still running) if status in ["queued", "running"]: client.cancel_job(job_id) print(f"\nCancelled job {job_id[:8]}...")

6. Context Manager Pattern¶

In [ ]:

from microDC import Client, LLMCall

# Using context manager ensures proper cleanup
with Client() as client:
    job = LLMCall(model="llama3.3")
    job.add_user_message("What is the meaning of life?")

    job_id = client.send_job(job)
    client.wait_for_all()

    result = client.get_job_details(job_id)
    print(result.result)

# Client is automatically cleaned up here

from microDC import Client, LLMCall # Using context manager ensures proper cleanup with Client() as client: job = LLMCall(model="llama3.3") job.add_user_message("What is the meaning of life?") job_id = client.send_job(job) client.wait_for_all() result = client.get_job_details(job_id) print(result.result) # Client is automatically cleaned up here

Next Steps¶

• Check out 02_simple_rag.ipynb for a complete RAG implementation using MicroDC
• See 03_batch_processing.ipynb for handling large-scale inference jobs
• Read the API documentation for more details