Metadata-Version: 2.4
Name: semantik-sdk
Version: 0.1.2
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

```bash
pip install semantik-sdk
# or with uv:
uv pip install semantik-sdk
```

## Quick Start

```python
from semantik import Semantik
import base64

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

# Or 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']}")
```

## Configuration

### API Key

Set your API key as an environment variable (recommended):

```bash
export SEMANTIK_API_KEY=sk_your_api_key_here
```

Or pass it directly to the client:

```python
client = Semantik(api_key="sk_your_api_key_here")
```

### Base URL

The SDK defaults to production (`https://gateway.semantikmatch.com`). For local development:

```python
client = Semantik(
    api_key="sk_...",
    base_url="http://localhost:9000"
)
```

Or set `SEMANTIK_BASE_URL` environment variable.

## API Reference

### Programs

- `client.programs.list()` - List all programs
- `client.programs.get(program_id)` - Get a specific program
- `client.programs.list_candidates(program_id, step_id=None, status=None, search=None, include=None, limit=None, cursor=None)` - List candidates in a program
- `client.programs.move_candidate(program_id, candidate_id, direction="next"|"previous", from_step_id=None, to_step_id=None)` - Move a candidate between steps

### Candidates

- `client.candidates.submit_application(candidate, program_id, step_id, client_data=None, documents=None)` - Submit a new application
- `client.candidates.get_status(candidate_id, include=None)` - Get candidate status across all programs
- `client.candidates.get_applications(candidate_id, include=None)` - Get all applications for a candidate
- `client.candidates.get_scores(candidate_id, include=None)` - Get candidate scores
- `client.candidates.enroll(candidate_id, program_id, step_id=None, send_email=None, email_template=None)` - Enroll candidate in a program

## Error Handling

```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 includes full type hints for better IDE support and type checking.

## Support

For issues or questions, please contact support or visit the [documentation](https://docs.semantikmatch.com).
