Metadata-Version: 2.4
Name: aiondtech
Version: 2.1.0
Summary: Official Python SDK for AiondTech Resume Analyser API
Author-email: AiondTech <support@aiondtech.com>
Maintainer-email: AiondTech <support@aiondtech.com>
License: MIT
Project-URL: Homepage, https://aiondtech.com
Project-URL: Documentation, https://docs.aiondtech.com
Project-URL: Repository, https://github.com/aiondtech/aiondtech-python
Project-URL: Bug Tracker, https://github.com/aiondtech/aiondtech-python/issues
Project-URL: Changelog, https://github.com/aiondtech/aiondtech-python/blob/main/CHANGELOG.md
Keywords: aiondtech,resume,cv,parser,analyzer,ats,recruitment,hr,api,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# AiondTech Resume Analyser SDK

Official Python SDK for the [AiondTech Resume Analyser API](https://aiondtech.com).

[![PyPI version](https://badge.fury.io/py/aiondtech.svg)](https://badge.fury.io/py/aiondtech)
[![Python Versions](https://img.shields.io/pypi/pyversions/aiondtech.svg)](https://pypi.org/project/aiondtech/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
pip install aiondtech
```

## Quick Start

```python
from aiondtech import ResumeAnalyser

# Initialize client
client = ResumeAnalyser(api_key="your-api-key")

# Or use environment variable
# export AIONDTECH_API_KEY="your-api-key"
client = ResumeAnalyser()

# Production mode
client = ResumeAnalyser(api_key="your-api-key", production=True)
```

### Constructor Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | `str` | `None` | API key (or set `AIONDTECH_API_KEY` env var) |
| `base_url` | `str` | `None` | Custom API base URL |
| `timeout` | `int` | `120` | Request timeout in seconds |
| `production` | `bool` | `False` | Use production URL (`https://api.aiondtech.com`) |

---

## API Endpoints

| Method | Credits | Description |
|--------|---------|-------------|
| `resumes.upload()` | 1 | Upload PDF resume |
| `resumes.upload_and_analyze()` | 3 | Upload + AI parsing |
| `resumes.upload_analyze_compare()` | 6 | Upload + parse + compare to job |
| `resumes.analyze()` | 2 | Parse existing resume by ID |
| `resumes.compare_resumes()` | 3 | Compare resume to job |
| `resumes.list()` | 0 | List all resumes |
| `jobs.create()` | 1 | Create job posting |
| `jobs.list()` | 0 | List all jobs |
| `credits.balance()` | 0 | Check credit balance |
| `credits.usage()` | 0 | View usage history |

---

## Detailed Usage

### 1. Upload Resume

Upload a PDF resume without parsing. Returns a `resume_id` for later use.

```python
result = client.resumes.upload("path/to/resume.pdf")
```

**Return type:** `ResumeUploadResult`

```python
result.resume_id     # int — Unique resume ID
result.message       # str — "Resume uploaded successfully"
result.credits_used  # int — 1
result._raw          # dict — Full raw API response
```

---

### 2. Upload and Analyze Resume

Upload a PDF and immediately extract structured data (AI-powered parsing).

```python
result = client.resumes.upload_and_analyze("path/to/resume.pdf")
```

**Return type:** `ResumeAnalysisResult`

```python
result.resume_id     # int — Unique resume ID
result.parsed_data   # dict — Full parsed data (see structure below)
result.credits_used  # int — 3
result._raw          # dict — Full raw API response

# Convenience properties
result.full_name         # str | None
result.email             # str | None
result.skills            # list[str]
result.job_titles        # list[str]
result.total_experience  # str | None
```

**`parsed_data` structure:**

```python
{
    "full_name": "John Doe",
    "email": "john@example.com",
    "contact_number": "+1234567890",
    "linkedin": "linkedin.com/in/johndoe",
    "location": "New York, NY",
    "skills": ["Python", "Django", "AWS"],
    "job_titles": ["Senior Developer", "Tech Lead"],
    "companies": ["Google", "Meta"],
    "education": ["BSc Computer Science - MIT"],
    "total_experience": "8 years",
    "certifications": ["AWS Certified Solutions Architect"],
    "summary": "Experienced software engineer..."
}
```

---

### 3. Upload, Analyze, and Compare

Upload a resume, parse it, and compare against a job posting in one call.

```python
result = client.resumes.upload_analyze_compare("resume.pdf", job_id=42)
```

**Return type:** `ResumeComparisonResult`

```python
result.resume_id         # int — Resume ID
result.job_id            # int — Job ID compared against
result.comparison_score  # float — Match score (0-100)
result.comparison_reason # str — Detailed reasoning
result.language          # str | None — Detected language (e.g. "en", "ar")
result.parsed_data       # dict | None — Parsed resume data
result.credits_used      # int — 6
result._raw              # dict — Full raw API response
```

---

### 4. Analyze Resume by ID

Parse an already-uploaded resume by its ID.

```python
result = client.resumes.analyze(resume_id=123)
```

**Return type:** `ParsedResumeResult`

```python
result.resume_id     # int — Resume ID
result.partner       # str — Partner identifier
result.parsed_data   # dict — Full parsed data
result.credits_used  # int — 2
result._raw          # dict — Full raw API response

# Convenience properties
result.full_name         # str | None
result.email             # str | None
result.phone             # str | None
result.linkedin          # str | None
result.location          # str | None
result.skills            # list[str]
result.job_titles        # list[str]
result.companies         # list[str]
result.education         # list[str]
result.total_experience  # str | None
result.certifications    # list[str]
```

---

### 5. Create Job Posting

Create a new job posting to compare resumes against.

```python
job = client.jobs.create(
    title="Senior Python Developer",
    description="We are looking for an experienced Python developer..."
)
```

**Return type:** `JobResult`

```python
job.job_id       # int — Unique job ID
job.title        # str — Job title
job.description  # str — Job description
job.created_by   # str — Creator identifier
job.created_at   # str | None — Creation timestamp
job.credits_used # int — 1
job._raw         # dict — Full raw API response
```

---

### 6. Compare Resume to Job

Compare an existing resume against an existing job posting.

```python
result = client.resumes.compare_resumes(resume_id=123, job_id=456)
```

**Return type:** `ResumeComparisonResult`

```python
result.resume_id         # int — Resume ID
result.job_id            # int — Job ID
result.comparison_score  # float — Match score (0-100)
result.comparison_reason # str — Detailed reasoning
result.language          # str | None — Detected language (e.g. "en", "ar")
result.credits_used      # int — 3
result._raw              # dict — Full raw API response
```

---

### 7. List Resumes

List all uploaded resumes with pagination.

```python
result = client.resumes.list(page=1, limit=50)
```

**Return type:** `ResumeListResult`

```python
result.resumes   # list[dict] — List of resume objects
result.total     # int — Total number of resumes
result.page      # int — Current page
result.limit     # int — Items per page
result.has_more  # bool — Whether more pages exist
result._raw      # dict — Full raw API response

# Iterable
for resume in result:
    print(resume["id"], resume.get("full_name"))

len(result)  # Number of resumes on this page
```

---

### 8. List Jobs

List all job postings with pagination.

```python
result = client.jobs.list(page=1, limit=50)
```

**Return type:** `JobListResult`

```python
result.jobs      # list[dict] — List of job objects
result.total     # int — Total number of jobs
result.page      # int — Current page
result.limit     # int — Items per page
result.has_more  # bool — Whether more pages exist
result._raw      # dict — Full raw API response

# Iterable
for job in result:
    print(job["id"], job["title"])
```

---

### 9. Check Credit Balance

```python
balance = client.credits.balance()
```

**Returns:** `dict`

```python
{
    "total": 1000,
    "used_mtd": 150,
    "remaining": 850,
    "plan_name": "Professional",
    "resets_at": "2026-03-01T00:00:00Z"
}
```

---

### 10. Credit Usage History

```python
usage = client.credits.usage()
# Or with date filters
usage = client.credits.usage(start_date="2026-01-01", end_date="2026-01-31")
```

---

## Error Handling

```python
from aiondtech import (
    ResumeAnalyser,
    APIError,
    AuthenticationError,
    InsufficientCreditsError,
    ValidationError,
    NotFoundError,
    RateLimitError,
)

client = ResumeAnalyser(api_key="your-api-key")

try:
    result = client.resumes.upload_and_analyze("resume.pdf")
except AuthenticationError as e:
    print(f"Invalid API key: {e}")
except InsufficientCreditsError as e:
    print(f"Not enough credits: {e}")
    print(f"Remaining: {e.credits_remaining}")
    print(f"Required: {e.credits_required}")
except ValidationError as e:
    print(f"Invalid input: {e}")
except NotFoundError as e:
    print(f"Resource not found: {e}")
except RateLimitError as e:
    print(f"Rate limited. Retry after: {e.retry_after} seconds")
except APIError as e:
    print(f"API error [{e.status_code}]: {e.message}")
```

---

## Complete Workflow Example

```python
from aiondtech import ResumeAnalyser

client = ResumeAnalyser(api_key="your-api-key")

# Step 1: Create a job posting
job = client.jobs.create(
    title="Senior Python Developer",
    description="5+ years Python, Django, AWS, PostgreSQL required..."
)
print(f"Created job #{job.job_id}: {job.title}")

# Step 2: Upload and analyze a resume
analysis = client.resumes.upload_and_analyze("candidate_resume.pdf")
print(f"Candidate: {analysis.full_name}")
print(f"Skills: {', '.join(analysis.skills)}")
print(f"Experience: {analysis.total_experience}")

# Step 3: Compare resume to job
comparison = client.resumes.compare_resumes(
    resume_id=analysis.resume_id,
    job_id=job.job_id
)
print(f"Score: {comparison.comparison_score}%")
print(f"Language: {comparison.language}")
print(f"Reasoning: {comparison.comparison_reason}")

# Step 4: Check remaining credits
balance = client.credits.balance()
print(f"Credits remaining: {balance['remaining']}")
```

### One-Step Workflow (Upload + Analyze + Compare)

```python
result = client.resumes.upload_analyze_compare("resume.pdf", job_id=job.job_id)
print(f"Score: {result.comparison_score}% — {result.comparison_reason}")
```

### Batch Processing

```python
import os

job = client.jobs.create("Data Scientist", "ML, Python, statistics...")

results = []
for pdf in os.listdir("resumes/"):
    if pdf.endswith(".pdf"):
        r = client.resumes.upload_analyze_compare(
            f"resumes/{pdf}", job_id=job.job_id
        )
        results.append(r)
        print(f"{r.comparison_score:5.1f}% — {pdf}")

# Sort by score
results.sort(key=lambda x: x.comparison_score, reverse=True)
print(f"\nTop candidate: resume_id={results[0].resume_id} ({results[0].comparison_score}%)")
```

---

## Environment Variables

```bash
# Set your API key
export AIONDTECH_API_KEY="your-api-key"

# Optional: Custom base URL
export AIONDTECH_BASE_URL="https://api.aiondtech.com"
```

```python
from aiondtech import ResumeAnalyser

# Client automatically uses environment variables
client = ResumeAnalyser()
```

---

## Support

- **Documentation**: [https://docs.aiondtech.com](https://docs.aiondtech.com)
- **API Reference**: [https://api.aiondtech.com/docs](https://api.aiondtech.com/docs)
- **Email**: support@aiondtech.com
- **Issues**: [GitHub Issues](https://github.com/aiondtech/aiondtech-python/issues)

## License

MIT License - see [LICENSE](LICENSE) for details.
