semantik-sdk 0.1.0

Python SDK for the Semantik Client API

Semantik Python SDK

Python SDK for the Semantik Client API. Designed for Python 3.8+ applications.

Installation

Prerequisites

Install uv (fast Python package manager):

curl -LsSf https://astral.sh/uv/install.sh | sh
# or
brew install uv
# or
pip install uv

Option 1: Local Development (Current)

Since the package is not yet published to PyPI, install it locally:

cd semantik-sdk/python
uv pip install -e .

Or install from the repository root:

uv pip install -e semantik-sdk/python

Option 2: From Git Repository

If the repository is accessible via Git:

uv pip install git+https://github.com/your-org/semantik.git#subdirectory=semantik-sdk/python

Option 3: Published Package (Future)

Once published to PyPI:

uv pip install semantik-sdk
# or with uv's native support (when available)
uv add semantik-sdk

Quick Start

from semantik import Semantik
import base64

# Option 1: Automatically reads from SEMANTIK_API_KEY environment variable (recommended)
# Set SEMANTIK_API_KEY in your .env file or environment
client = Semantik()

# Option 2: Override with explicit API key
client = Semantik(api_key="sk_your_api_key_here")

# List programs
programs_response = client.programs.list()
print(f"Found {len(programs_response['programs'])} programs")

# Get a specific program
program = client.programs.get(programs_response['programs'][0]['id'])

# Submit a candidate application
with open('resume.pdf', 'rb') as f:
    cv_content = base64.b64encode(f.read()).decode('utf-8')

result = client.candidates.submit_application(
    candidate={
        "firstName": "John",
        "lastName": "Doe",
        "email": "[e-mail]"
    },
    program_id=program['id'],
    step_id=program['steps'][0]['id'],
    documents=[
        {
            "fieldName": "CV",
            "content": cv_content,
            "fileName": "john-doe-cv.pdf",
            "mimeType": "application/pdf",
            "encoding": "base64"
        }
    ]
)

print(f"Application submitted: {result['applicationId']}")
print(f"Candidate ID: {result['candidateId']}")

# Get candidate status
status = client.candidates.get_status(result['candidateId'], include="applications,scores")
print(f"Candidate: {status['candidate']['firstName']} {status['candidate']['lastName']}")

# Move candidate to next step
move_result = client.programs.move_candidate(
    program_id=program['id'],
    candidate_id=result['candidateId'],
    direction="next"
)
print(f"Moved from {move_result['movement']['from']['name']} to {move_result['movement']['to']['name']}")

Environment Variables

The SDK automatically reads from environment variables:

• SEMANTIK_API_KEY (required): Your API key
• SEMANTIK_BASE_URL (optional): API base URL (defaults to https://gateway.semantikmatch.com)

Base URL Configuration

The SDK defaults to calling the production gateway service at https://gateway.semantikmatch.com. This is where all /api/v2/ endpoints are hosted.

For local development, override the base URL:

# Via constructor
client = Semantik(
    api_key="sk_...",
    base_url="http://localhost:9000"  # Your local gateway service
)

# Or via environment variable
import os
os.environ["SEMANTIK_BASE_URL"] = "http://localhost:9000"
client = Semantik()

For different environments:

• Production: https://gateway.semantikmatch.com (default)
• Local: http://localhost:9000
• Staging: https://gateway-staging.semantikmatch.com (example)

API Reference

Programs

• client.programs.list() - List all programs
• client.programs.get(program_id) - Get a specific program
• client.programs.list_candidates(program_id, ...) - List candidates in a program
• client.programs.move_candidate(program_id, candidate_id, ...) - Move a candidate between steps

Candidates

• client.candidates.submit_application(...) - Submit a new application
• client.candidates.get_status(candidate_id, include=...) - Get candidate status
• client.candidates.get_applications(candidate_id, include=...) - Get all applications
• client.candidates.get_scores(candidate_id, include=...) - Get candidate scores
• client.candidates.enroll(candidate_id, program_id, ...) - Enroll candidate in a program

Error Handling

The SDK raises ApiError for API-related errors:

from semantik import Semantik, ApiError

try:
    program = client.programs.get(999)
except ApiError as e:
    print(f"API Error {e.status}: {e}")
    print(f"Path: {e.path}")
    print(f"Response: {e.response}")
except Exception as e:
    print(f"Unexpected error: {e}")

Type Hints

The SDK uses Python type hints for better IDE support. All methods are annotated with their return types.

Development

# Install in development mode
uv pip install -e .

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
python scripts/test_all_endpoints.py
# or
uv run python scripts/test_all_endpoints.py

# Format code
uv run black semantik/

# Type checking
uv run mypy semantik/

Documentation

For complete API documentation, see the JavaScript SDK Documentation which covers all endpoints. The Python SDK mirrors the same API structure.

Support

For issues, questions, or contributions, please refer to the main repository documentation or contact support.