Metadata-Version: 2.4
Name: semantik-sdk
Version: 0.1.0
Summary: Python SDK for the Semantik Client API
Author-email: Semantik <support@semantikmatch.com>
License: MIT
Project-URL: Homepage, https://github.com/your-org/semantik
Project-URL: Documentation, https://docs.semantikmatch.com
Project-URL: Repository, https://github.com/your-org/semantik
Keywords: semantik,sdk,api,students
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: requires-python

# Semantik Python SDK

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

## Installation

### Prerequisites

Install `uv` (fast Python package manager):
```bash
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:

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

Or install from the repository root:

```bash
uv pip install -e semantik-sdk/python
```

### Option 2: From Git Repository

If the repository is accessible via Git:

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

### Option 3: Published Package (Future)

Once published to PyPI:

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

## Quick Start

```python
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": "john.doe@example.com"
    },
    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:

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

```python
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

```bash
# 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](../javascript/DOCUMENTATION.md) 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.
