Installation

The Ragnerock Python SDK provides a high-level interface to interact with the Ragnerock platform. This guide will help you get up and running quickly.

Requirements

• Python 3.9 or higher
• A Ragnerock account with access to a project

Installation

Install the SDK using pip:

pip install ragnerock

Or with uv:

uv add ragnerock

Optional Dependencies

For pandas DataFrame support in query results:

pip install ragnerock[pandas]

Connecting to Ragnerock

The SDK uses a connection string to authenticate and connect to your project:

from ragnerock import create_engine, Session

engine = create_engine("ragnerock://your.email@company.com:password@api.ragnerock.com/your_project")

with Session(engine) as session:
    # You're connected!
    pass

Connection String Format

ragnerock://email:password@host/project_name

Component	Description
email	Your Ragnerock account email
password	Your account password
host	API host (typically api.ragnerock.com)
project_name	The name of your project

Using Environment Variables

For security, avoid hardcoding credentials. Use environment variables instead:

export RAGNEROCK_EMAIL="your.email@company.com"
export RAGNEROCK_PASSWORD="your-password"
export RAGNEROCK_PROJECT="your_project"

import os
from ragnerock import create_engine, Session

email = os.environ["RAGNEROCK_EMAIL"]
password = os.environ["RAGNEROCK_PASSWORD"]
project = os.environ["RAGNEROCK_PROJECT"]

engine = create_engine(f"ragnerock://{email}:{password}@api.ragnerock.com/{project}")

with Session(engine) as session:
    # Connected with credentials from environment
    pass

Verifying Your Installation

Run a quick test to verify everything is working:

from ragnerock import create_engine, Session, Document

engine = create_engine("ragnerock://your.email@company.com:password@api.ragnerock.com/your_project")

with Session(engine) as session:
    # List documents in your project
    docs = session.list(Document).all()
    print(f"Found {len(docs)} documents")

    # Get a specific document
    if docs:
        doc = docs[0]
        print(f"First document: {doc.name}")
        print(f"Status: {doc.status}")

If you see document information printed, your installation is working correctly.

Troubleshooting

Authentication Errors

If you get an AuthenticationError:

1. Verify your email and password are correct
2. Check that your account has access to the specified project
3. Ensure special characters in your password are URL-encoded

from urllib.parse import quote

password = quote("p@ss/word!", safe="")
engine = create_engine(f"ragnerock://email:{password}@api.ragnerock.com/project")

Connection Errors

If you can’t connect to the API:

1. Check your internet connection
2. Verify the host is correct (api.ragnerock.com for production)
3. Ensure any corporate firewall allows connections to the Ragnerock API

Project Not Found

If you get a NotFoundError for the project:

1. Verify the project name is spelled correctly
2. Confirm your account has access to this project
3. Check with your administrator if the project exists

Next Steps

Now that you have the SDK installed, head over to the Quick Start guide to upload your first document and run your first annotation workflow.