Core Classes Reference

SJM Core Classes

Comprehensive guide to SJM's main components

SJM Client Class

The SJM class is the primary entry point for all API interactions. It provides methods for matching, skill verification, interviews, and more.

from sjm import SJM

# Initialize the client
client = SJM(api_key="your_api_key")

# Check API health
health = client.health()
print(f"API Status: {health['status']}")

# Use other methods
matches = client.match(...)
skill_result = client.verify_skill(...)
interview = client.interview(...)
1
2
3
4
5
6
7
8
9
10
11
12
13

Client Configuration

When initializing the SJM client, you can provide configuration options:

from sjm import SJM

# Basic initialization
client = SJM(api_key="your_api_key")

# With additional configuration
client = SJM(
  api_key="your_api_key",
  # These parameters are optional
  base_url="https://custom-domain.com/api/v1",  # Custom base URL (if needed)
  timeout=60  # Request timeout in seconds
)
1
2
3
4
5
6
7
8
9
10
11
12

Core Methods

Match Method

The match method is used to find freelancers that match a project's requirements.

from sjm import SJM

client = SJM(api_key="your_api_key")

# Basic matching
matches = client.match(
  description="Build a modern web application with React and Node.js",
  required_skills=["React.js", "Node.js", "TypeScript"],
  budget_range=(5000, 10000),
  complexity="medium",
  timeline=30
)

# Process results
for match in matches["matches"][:3]:
  freelancer = match["freelancer"]
  print(f"Match: {freelancer['name']} ({freelancer['job_title']})")
  print(f"Score: {match['score']:.2f}")
  print(f"Matching Skills: {match['matching_skills']}")
  print(f"Hourly Rate: 85/hr")
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

Match Parameters

Required Parameters

  • description: String describing the project requirements
  • required_skills: List of skills required for the project

Optional Parameters

  • budget_range: Tuple/array of (min, max) budget in USD
  • complexity: Project complexity ("low", "medium", "high")
  • timeline: Project timeline in days
  • weights: Dictionary of matching weights for different factors

Verify Skill Method

The verify_skill method checks if a skill exists in the SJM database and finds similar skills when an exact match isn't found.

from sjm import SJM

client = SJM(api_key="your_api_key")

# Verify a skill
result = client.verify_skill("React.js")

# Check if the skill exists
if result["data"]["exists"]:
  print(f"✅ The skill 'React.js' is verified in the database")
  if "skills" in result["data"]:
      print(f"Matching skills: {', '.join(result['data']['skills'])}")
else:
  print(f"❌ The skill 'React.js' is not verified")
  if result["data"]["similar_terms"]:
      print(f"Did you mean: {', '.join(result['data']['similar_terms'])}")
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Verify Skill Response

{
"status": "success",
"data": {
  "exists": true,        // Whether the skill exists in the database
  "similar_terms": [],   // Similar skills (if the skill doesn't exist)
  "type": "skill",       // Type: "skill" or "job_title" or null
  "matches": ["React.js"], // Exact matches found
  "skills": ["React.js"],  // Matching skills
  "job_titles": []       // Matching job titles (if any)
}
}
1
2
3
4
5
6
7
8
9
10
11

Interview Method

The interview method handles AI-powered technical interviews, including question generation and response evaluation.

from sjm import SJM

client = SJM(api_key="your_api_key")

# Step 1: Generate interview questions
interview = client.interview(
  freelancer_id="f123",
  project_description="Build a modern web application with React",
  required_skills=["React.js", "Node.js", "TypeScript"],
  job_title="Full Stack Developer",
  mode="ai_questions"
)

# Get session ID and questions
session_id = interview["data"]["session_id"]
questions = interview["data"]["interview_data"]["questions"]

# Display questions
for i, q in enumerate(questions, 1):
  print(f"Q{i}: {q['text']}")

# Step 2: Collect candidate answers (simulated in this example)
answers = [
  "I have 5 years of experience with React...",
  "For state management, I prefer using Redux...",
  "My approach to testing includes Jest and React Testing Library..."
]

# Step 3: Evaluate responses
evaluation = client.interview(
  freelancer_id="f123",
  project_description="Build a modern web application with React",
  required_skills=["React.js", "Node.js", "TypeScript"],
  job_title="Full Stack Developer",
  mode="ai_full",
  session_id=session_id,
  provided_answers=answers
)

# Process evaluation results
if "evaluation" in evaluation["data"]:
  eval_data = evaluation["data"]["evaluation"]
  print(f"Overall Score: {eval_data['overall_score']}/100")
  print(f"Strengths: {', '.join(eval_data['strengths'])}")
  print(f"Areas for Improvement: {', '.join(eval_data['areas_for_improvement'])}")
  print(f"Hiring Recommendation: {'Yes' if eval_data['hiring_recommendation'] else 'No'}")
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

Interview Parameters

Required Parameters

  • freelancer_id: ID of the freelancer
  • project_description: Description of the project
  • required_skills: List of required skills
  • job_title: Job title for the position
  • mode: Interview mode ("ai_full", "ai_questions", "custom_full", "hybrid")

Optional Parameters

  • session_id: Session ID for continuing interviews
  • provided_answers: Answers for evaluation (used with "ai_full" mode)
  • custom_questions: Custom questions (used with "custom_full" mode)
  • scoring_criteria: Custom scoring criteria
  • additional_questions: Additional questions (used with "hybrid" mode)

Parse Resume Method

The parse_resume method extracts skills and other information from resume files.

from sjm import SJM

client = SJM(api_key="your_api_key")

# Parse a resume file
resume_data = client.parse_resume("resume.pdf")

# Extract skills and other information
if resume_data["status"] == "success":
  skills = resume_data["data"]["skills"]
  print(f"Extracted Skills: {', '.join(skills)}")
  
  # Check education and experience if available
  if resume_data["data"]["education"]:
      print(f"Education: {resume_data['data']['education']}")
  
  if resume_data["data"]["experience"]:
      print(f"Experience: {resume_data['data']['experience']}")
  
  # Check contact information
  if resume_data["data"]["contact"]:
      contact = resume_data["data"]["contact"]
      print(f"Email: {contact.get('email')}")
      print(f"Phone: {contact.get('phone')}")
      print(f"Location: {contact.get('location')}")
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

Generate Test Data Method

The generate_test_data method creates test freelancer data for development and testing.

from sjm import SJM

client = SJM(api_key="your_api_key")

# Generate test freelancer data
test_data = client.generate_test_data(num_freelancers=100)

# Process the generated data
freelancers = test_data["data"]
print(f"Generated {len(freelancers)} test freelancers")

# Display sample freelancers
for freelancer in freelancers[:3]:
  print(f"
{freelancer['name']} - {freelancer['job_title']}")
  print(f"  Skills: {freelancer['skills']}")
  print(f"  Experience: {freelancer['experience']} years")
  print(f"  Rating: {freelancer['rating']}/5")
  print(f"  Hourly Rate: 85/hr")
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Health Check Method

The health method checks the status of the SJM API and its components.

from sjm import SJM

client = SJM(api_key="your_api_key")

# Check API health
health = client.health()

# Display health status
print(f"API Status: {health['status']}")

if "components" in health:
  print("
Component Status:")
  for component, status in health["components"].items():
      component_status = status.get("status", "unknown")
      status_icon = "✅" if component_status == "healthy" else "❌"
      print(f"{status_icon} {component}: {component_status}")
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Error Handling

Both the Python and JavaScript SDKs provide error handling patterns for handling various types of errors.

from sjm import SJM, SJMError, SJMAuthenticationError, SJMRateLimitError, SJMAPIError

client = SJM(api_key="your_api_key")

try:
  # Make an API call
  result = client.match(
      description="Project description",
      required_skills=["React.js", "Node.js"]
  )
  
  # Process the result
  print(f"Found {len(result['matches'])} matches")
  
except SJMAuthenticationError as e:
  print(f"Authentication failed: {e}")
  # Handle authentication issues (check API key, etc.)
  
except SJMRateLimitError as e:
  print(f"Rate limit exceeded. Reset in {e.reset_at} seconds")
  # Implement retry logic or wait before trying again
  
except SJMAPIError as e:
  print(f"API error: {e}")
  # Handle API errors (bad request, server error, etc.)
  
except SJMError as e:
  print(f"General error: {e}")
  # Handle all other SJM errors
  
except Exception as e:
  print(f"Unexpected error: {e}")
  # Handle any other unexpected errors
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

CLI Interface

The SJM package includes a command-line interface for convenient access to API functions:

# Set your API key as an environment variable (recommended)
export SJM_API_KEY="your_api_key"

# Check API health
sjm health

# Match freelancers to a project
sjm match --description "Web development project" --skills "React.js,Node.js,TypeScript"

# Verify if a skill exists in the database
sjm verify-skill "React.js"

# Generate test data
sjm generate-test-data --number 10

# Start interactive mode
sjm interactive

# Display help
sjm --help
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

TypeScript Support

The Node.js SDK includes full TypeScript support with type definitions for all methods, parameters, and responses:

import { 
SJM, 
SJMConfig, 
MatchParams, 
MatchResponse, 
InterviewParams,
Freelancer,
MatchResult
} from 'sjm';

// Use type-safe parameters
const params: MatchParams = {
description: "Build a web app",
required_skills: ["React.js", "Node.js"],
budget_range: [5000, 10000],
complexity: "medium",
timeline: 30
};

// Type-safe response handling
const client = new SJM({ apiKey: "your_api_key" });
const result: MatchResponse = await client.match(params);
const matches: MatchResult[] = result.matches;
const topFreelancer: Freelancer = matches[0].freelancer;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24