README.md

---
title: talentum-score
app_file: testing_app.py
sdk: gradio
sdk_version: 5.39.0
---
# Talentum Score

A Python-based job evaluation system that helps job seekers identify red flags about companies and analyze job postings using AI-powered web search and analysis.

## Overview

Talentum Score is designed to assist job seekers in making informed career decisions by analyzing companies for potential red flags such as layoffs, poor management, toxic culture, financial instability, or legal issues. The system uses advanced AI models to search and analyze publicly available information about companies and provide comprehensive evaluations.

## Features

- **Company Red Flag Analysis**: Automatically searches for and identifies potential red flags about companies
- **Job Posting Evaluation**: Analyzes job descriptions for concerning patterns
- **AI-Powered Research**: Uses Perplexity AI for comprehensive web search and analysis
- **Modular Architecture**: Built with a flexible node-based system for extensible functionality
- **Structured Output**: Provides scored evaluations with detailed analysis and source citations

## Technology Stack

- **Python 3.12+**: Modern Python with type hints
- **LangChain**: Framework for building LLM applications
- **Perplexity AI**: Advanced AI search and analysis capabilities
- **LangGraph**: State management for complex AI workflows
- **Pydantic**: Data validation and serialization
- **Pydantic Settings**: Configuration management

## Architecture

The system is built using a flow-based architecture with the following key components:

### Core Components

- **Domain Models** (`src/domain.py`): Pydantic models defining data structures
- **Flows** (`src/flows/`): Orchestrate complex multi-step processes
- **Nodes** (`src/nodes/`): Individual processing units that can be combined
- **Prompts** (`src/prompts/`): AI prompt templates for different analysis tasks

### Key Classes

- `JobPosting`: Represents a job posting with company name, position, and description
- `TalentumScoreResponse`: Final evaluation with score and analysis
- `CompanyEvaluation`: Company analysis with score, analysis text, and sources
- `PostEvaluation`: Job posting analysis with red flags and additional notes
- `WebSearchNode`: Performs AI-powered web searches using Perplexity
- `JobEvaluatorFlow`: Main flow orchestrating the complete evaluation process

## Installation

This project uses [uv](https://github.com/astral-sh/uv) for dependency management.

```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Activate the virtual environment
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate  # On Windows
```

## Usage

### Basic Example

```python
from src.domain import JobPosting
from src.flows.job_evaluator import JobEvaluatorFlow

# Create a job posting to evaluate
job_posting = JobPosting(
    company_name="Example Corp",
    position="Software Engineer",
    description="We are looking for a software engineer with 3 years of experience in Python and Django."
)

# Create and run the evaluation flow
evaluator = JobEvaluatorFlow()
result = evaluator.run(job_posting)

print(f"Score: {result.score}")
print(f"Analysis: {result.analysis}")
```

### Web Search Node Example

```python
from pathlib import Path
from src.nodes.web_search import WebSearchNode

# Create a web search node for company analysis
node = WebSearchNode(
    system_prompt_path=Path("src/prompts/search_company_info_system.txt"),
    query="Company Name: Google",
    model="sonar"  # Perplexity model
)

# Execute the search
state = {"flow_input": job_posting}
result_state = node.execute(state)
```

## Configuration

The system uses environment variables for configuration. Create a `.env` file in the project root:

```env
PERPLEXITY_API_KEY=your_perplexity_api_key_here
```

## Project Structure

```
talentum-score/
├── app.py                          # Main application entry point
├── pyproject.toml                  # Project configuration and dependencies
├── src/
│   ├── domain.py                   # Pydantic models and data structures
│   ├── flows/                      # Processing flows
│   │   ├── __init__.py
│   │   ├── base.py                 # Base flow classes and interfaces
│   │   └── job_evaluator.py        # Main job evaluation flow
│   ├── nodes/                      # Processing nodes
│   │   ├── base.py                 # Base node class
│   │   └── web_search.py           # Web search functionality
│   ├── prompts/                    # AI prompt templates
│   │   └── search_company_info_system.txt  # Company analysis prompt
│   └── README.md                   # This file
└── uv.lock                         # Dependency lock file
```

## Development

### Adding New Nodes

To create a new processing node:

1. Inherit from the `Node` base class
2. Implement the `execute` method
3. Define `name` and `description` attributes

```python
from src.nodes.base import Node
from src.flows.base import FlowState

class CustomNode(Node):
    name: str = "CustomNode"
    description: str = "Description of what this node does"
    
    def execute(self, state: FlowState) -> FlowState:
        # Your processing logic here
        return state
```

### Adding New Flows

To create a new flow:

1. Inherit from the `Flow` base class
2. Define input and output types
3. Implement the `get_state_graph` method

```python
from src.flows.base import Flow, FlowState
from langgraph.graph import StateGraph

class CustomFlow(Flow[InputType, OutputType]):
    def get_state_graph(self) -> StateGraph:
        graph_builder = StateGraph(self.state)
        # Add your nodes and connections
        return graph_builder.compile()
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

This project is part of the Talentum Core ecosystem. Please refer to the main repository for licensing information.

## Support

For support and questions, please refer to the main Talentum Core project documentation or create an issue in the repository.