feat: add Talent Angels graph agents for Learning Tokens

[iron-prog]

Summary

This PR adds a Python-based Talent Angels graph-agent framework to the Learning Tokens repository.

The implementation introduces deterministic graph reasoning agents that help users navigate relationships between skills, tasks, occupations, learning resources, assessments, and Learning Tokens. The work is inspired by the Talent Angels mentorship vision of using graph-based agents to explore and reason over skill taxonomies and learning pathways.

In addition to graph navigation, the PR connects Learning Token issuance previews with graph-based skill and occupation discovery, demonstrating how normalized LMS evidence can be transformed into skill-oriented recommendations.

---

Features Added

Talent Graph Framework

Added reusable graph primitives for representing:

• Skills
• Tasks
• Occupations
• Learning resources
• Assessments
• Learning Token relationships

Graph functionality includes:

• Node and edge modeling
• Graph serialization/deserialization
• Neighborhood traversal
• Path discovery
• Occupation recommendation

Locator Agent

Identifies graph locations matching a natural-language query.

• Examples: Skills, Tasks, Occupations

Connector Agent

Explores predecessor and successor nodes around a selected graph location.

• Examples: Prerequisite skills, Related tasks, Learning resources, Assessment relationships

Pathfinder Agent

Discovers learning and career pathways through the graph.

• Examples: Skill → Occupation, Course → Skill → Task, Learning Journey exploration

Learning Token Planner Agent

Combines Normalized LMS payloads, Learning Token issuance previews, and Talent graph reasoning to generate:

• Acquired skill inference
• Occupation recommendations
• Learning Token planning outputs

Seed Talent Graph Dataset

Added an example graph containing nodes and relationships inspired by:

• ESCO, ONET, SFIA, BLS, Lightcast, and Learning Tokens.

This provides a deterministic foundation for future integration with larger external taxonomies.

CLI Support

Added command-line workflows for: locate, connect, path, preview, and plan.

Example:

python -m tools.issuance_preview.learning_tokens_issuance.main locate "knowledge graph"

Normalized LMS Evidence
         ↓
Learning Token Issuance Preview
         ↓
   Skill Discovery
         ↓
Graph Navigation (Locator / Connector / Pathfinder)
         ↓
Occupation Recommendations

## Testing

Executed successfully:

bash python -m unittest discover -s tools/issuance_preview/tests -v 

Result:

text Ran 11 tests  OK 

Additional manual validation performed:

### Locator Agent

bash python -m tools.issuance_preview.learning_tokens_issuance.main \ locate "knowledge graph" \ --kind skill \ --pretty 

### Connector Agent

bash python -m tools.issuance_preview.learning_tokens_issuance.main \ connect "esco:skill:knowledge-graphs" \ --pretty 

### Pathfinder Agent

bash python -m tools.issuance_preview.learning_tokens_issuance.main \ path \ "lightcast:skill:python" \ "bls:occupation:software-developer" \ --pretty 

### Issuance Preview

bash python -m tools.issuance_preview.learning_tokens_issuance.main \ preview \ --payload examples/talent-angels-moodle.json \ --policy examples/policy.json \ --pretty 

### Planner

bash python -m tools.issuance_preview.learning_tokens_issuance.main \ plan \ --payload examples/talent-angels-moodle.json \ --policy examples/policy.json \ --pretty 

---

## Future Directions

This foundation can be extended with:

- Real ESCO ingestion
- ONET integration
- SFIA integration
- GraphRAG workflows
- Natural-language chat interfaces
- Learning path generation
- Skill gap analysis
- Learning Token-backed skill verification

The current implementation focuses on providing a lightweight, testable, deterministic graph-agent framework that can evolve toward those capabilities.

## AI Assistance

AI-assisted tooling was used during development for brainstorming implementation approaches, reviewing code structure, generating test ideas, and improving documentation.

All design decisions, code integration, debugging, testing, validation, and final implementation were performed manually. The contributor reviewed and modified generated suggestions as needed and verified functionality through automated tests and local execution before submission.

[iron-prog]

This PR implements a deterministic Talent Angels graph-agent framework for Learning Tokens, including Locator, Connector, Pathfinder, and Learning Token Planner agents. It demonstrates how normalized LMS evidence and Learning Token issuance previews can be connected to graph-based skill and occupation reasoning.

[ryjones]

@AlfonsoGovela

[iron-prog]

@AlfonsoGovela any update on this

[nosoypoot]

Hi @iron-prog, and sorry for the long silence. I maintain this repo and I mentor Talent Angels, so I can answer both halves.

First, the part you got right: connecting graph reasoning over skill taxonomies to Learning Token issuance is where both projects are going. It's on the Talent Angels roadmap explicitly, where the program goal is a working Locator/Connector/Pathfinder suite feeding the Learning Tokens Proof-of-Learning layer (ROADMAP.md). So the direction isn't the problem. The sequencing and the path are.

Why this can't land as-is

The convergence comes after the suites and the assistant exist, through a defined contract, not as a graph inside this repo. And Talent Angels made decisions after this PR was opened (May 30) that it predates:

• Three peer agents behind an orchestrator is the alternative we rejected by name. We went to one assistant with Locate / Connect / Pathfind / Evaluate as skills and deterministic tools (ADR-0003).
• Lightcast is out ($41–50k/yr per signed public contracts; their terms exclude commercial and AI use without a separate agreement; free tier ended Feb 2026 with three days' notice). SFIA is structure-only, and taxonomies link only through official crosswalks (ADR-0006). The seed graph wires ESCO → O*NET → BLS → Lightcast with hand-authored weights, which reads as source data but isn't.
• infer_acquired_skills matches assignment titles to skill labels by word overlap. Against this repo's real fixture, where the assignment is titled "Essay 1", it returns acquiredSkillIds: [] and still ranks two occupations at coverage: 0.0. For Proof-of-Learning, inferring an acquired ESCO skill from string overlap and placing it next to token issuance is the specific failure mode the architecture exists to avoid.

The issuance preview is the half that stands on its own

I ran preview.py against all four normalized fixtures in npm_package ltsdk (Moodle, Canvas, edX, Google Classroom) with one policy and no changes to your code. A dependency-free dry-run over normalized evidence before anything is minted is a real gap here. Without the graph layer, that's a reasonable candidate for this repo. I won't promise a review date, since my focus is Talent Angels right now.

It also found something. Writing one policy across the four surfaces this in our own SDK:

moodle           workflow_state = 'submitted'    submitted_at: yes
canvas           workflow_state = 'submitted'    submitted_at: yes
edx              workflow_state = 'graded'       submitted_at: NO
googleclassroom  workflow_state = 'unknown'      submitted_at: yes

Three vocabularies for one field. Today no attendance rule works across our four normalizers. That's a bug in our SDK, and your tool is what makes it fall out. Worth its own issue, credited to you.

I'll leave this PR open for now. If you strip it down to the preview, it stays your PR and your commits. If I don't hear back in a few weeks I'll close it as stale, which doesn't erase anything: the branch and the attribution stay on the repo either way.

On Talent Angels

The mentee cohort is selected through the LFX Mentorship program and is already formed, so there's no joining the sprint work mid-programme. But the repos are open source and CONTRIBUTING.md applies to anyone: open an issue, a mentor scopes it with you, then a PR with DCO sign-off and one mentor approval. I'm one of the reviewers there.

One request though, and I mean it kindly: open an issue and let me scope it before you write anything. A 1,500-line PR against constraints you can't see is expensive for both of us, and this one sat two months for exactly that reason. A scoped issue gets an answer from me in days.

[iron-prog]

Hi @ghosind,

Thanks for the detailed review and for keeping the PR open.

I understand the main point now: the graph-agent layer doesn't fit the current direction of this repository, while the issuance preview is the part that stands on its own. I also understand the concern about infer_acquired_skills() relying on assignment title overlap and producing acquiredSkillIds: [] with the real fixture. That's a fair observation.

I'll rework this PR to focus on the dependency-free issuance preview workflow and remove the graph-related pieces. For future work, I'll open a scoped issue first and discuss the approach before starting implementation so it aligns with the current architecture and roadmap.

I'm also glad the issuance preview helped uncover the workflow state inconsistency across the LMS normalizers. That's an interesting finding, and I'm happy it was useful.

Thanks once again for the guidance and the detailed explanation. I appreciate you leaving the PR open so I can revise it, and I'll submit a smaller, better-scoped contribution.