riasec-co 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,115 @@
+# riasec-co
+
+**Connects each student's vocational profile with Colombia's 17,230 active SNIES programs.**
+
+Bayesian adaptive RIASEC engine with the complete SNIES catalog — 33 departments, 297 institutions. Zero runtime dependencies.
+
+[![npm](https://img.shields.io/npm/v/riasec-co)](https://www.npmjs.com/package/riasec-co)
+[![CI](https://github.com/affromero/riasec-co/actions/workflows/ci.yml/badge.svg)](https://github.com/affromero/riasec-co/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+## Install
+
+```bash
+npm install riasec-co
+```
+
+## Quick Start
+
+```typescript
+import { createQuiz, loadPrograms, recommend } from 'riasec-co'
+
+// 1. Run adaptive quiz (~12 questions instead of 48)
+const quiz = createQuiz({ language: 'es', mode: 'adaptive' })
+while (!quiz.isComplete()) {
+  const q = quiz.nextQuestion()!
+  const response = await askUser(q.text) // your UI
+  quiz.answer(q.id, response)
+}
+
+console.log(quiz.profile())
+// { R: 0.19, I: 0.27, A: 0.10, S: 0.16, E: 0.10, C: 0.18 }
+console.log(quiz.topTypes(2)) // ['I', 'R']
+
+// 2. Get program recommendations
+const results = recommend({
+  profile: quiz.profile(),
+  programs: loadPrograms(),
+  filters: { departments: ['Sucre', 'Cordoba', 'Bolivar'], active: true },
+  priors: { enrollmentWeight: -0.3, virtualBoost: 1.5 },
+  limit: 10,
+})
+
+results.forEach((r, i) =>
+  console.log(`${i + 1}. ${r.program.nombre_programa} (${r.score.toFixed(2)})`)
+)
+```
+
+## API
+
+### Quiz
+
+| Function | Description |
+|----------|-------------|
+| `createQuiz(config?)` | Create a quiz instance (`language`: `"es"` or `"en"`, `mode`: `"adaptive"` or `"full"`) |
+| `quiz.nextQuestion()` | Next item (or `null` if complete) |
+| `quiz.answer(id, response)` | Record a Likert response (1-5) |
+| `quiz.isComplete()` | Whether the quiz has enough information to stop |
+| `quiz.profile()` | Current RIASEC profile (`RIASECProfile`) |
+| `quiz.topTypes(n?)` | Top N types sorted by probability |
+| `quiz.progress()` | `{ answered, total, estimatedRemaining, confidence, entropy }` |
+
+### Data
+
+| Function | Description |
+|----------|-------------|
+| `loadPrograms()` | All 30,809 SNIES programs (17,230 active) |
+| `loadItems(language)` | 48 IPIP items in `"es"` or `"en"` |
+| `loadMapping()` | RIASEC → CINE field weights |
+| `getCINEFields(programs)` | Unique CINE broad fields |
+| `getDepartments(programs)` | Unique departments |
+
+### Recommendations
+
+| Function | Description |
+|----------|-------------|
+| `recommend(config)` | Rank programs by profile fit, with enrollment priors and regional boosts |
+
+### Scoring Internals
+
+| Function | Description |
+|----------|-------------|
+| `uniformPrior()` | Dirichlet α = (1,1,1,1,1,1) |
+| `updateAlpha(alpha, type, response, keyed)` | Bayesian update after one answer |
+| `posteriorMean(alpha)` | E[θ_k] = α_k / Σα |
+| `entropy(alpha)` | Shannon entropy in bits |
+| `confidence(alpha)` | 1 − (entropy / max_entropy) |
+| `cosineSimilarity(a, b)` | Vector similarity [0, 1] |
+| `expectedInfoGain(alpha, type)` | Information gain for adaptive item selection |
+
+## How It Works
+
+1. **Dirichlet prior** — starts with uniform belief over 6 RIASEC types
+2. **Adaptive selection** — picks the question that maximizes expected information gain
+3. **Bayesian update** — each Likert response updates the posterior
+4. **Entropy stopping** — stops when Shannon entropy < 1.5 bits (~12 questions)
+5. **Program matching** — cosine similarity between profile and CINE field vectors
+6. **Enrollment priors** — downweights oversaturated fields, boosts underserved ones
+
+## Data
+
+Bundled in the package (no network requests):
+
+- **30,809 programs** from Colombia's SNIES/HECAA catalog (24 columns each)
+- **48 IPIP items** in English and Spanish (8 per RIASEC type)
+- **RIASEC → CINE mapping** with weighted associations
+
+## Also Available
+
+- **Python**: `pip install riasec-co` — [PyPI](https://pypi.org/project/riasec-co/)
+- **R**: `remotes::install_github("afromero/riasec-co", subdir = "r")`
+- **React components**: [`riasec-co-react`](https://www.npmjs.com/package/riasec-co-react)
+
+## License
+
+MIT

package/data/items_en.json

@@ -3,6 +3,8 @@
     "source": "International Personality Item Pool (ipip.ori.org)",
     "scale": "IPIP Basic Interest Markers",
     "reference": "Liao, H.-Y., Armstrong, P. I., & Rounds, J. (2008). Development and initial validation of public domain Basic Interest Markers. Journal of Vocational Behavior, 73(1), 159-183.",
+    "reference_doi": "10.1016/j.jvb.2007.12.002",
+    "reference_url": "https://doi.org/10.1016/j.jvb.2007.12.002",
     "license": "Public domain",
     "response_scale": {
       "1": "Very inaccurate",

package/data/items_es.json

@@ -1,8 +1,10 @@
 {
   "meta": {
     "source": "International Personality Item Pool (ipip.ori.org)",
-    "scale": "IPIP Basic Interest Markers — Spanish adaptation",
-    "reference": "Armstrong, P. I., Allison, W., & Rounds, J. (2020). Alternate Forms Public Domain RIASEC Markers. Electronic Journal of Research in Educational Psychology.",
+    "scale": "IPIP Basic Interest Markers, Spanish (Río de la Plata) adaptation",
+    "reference": "Cupani, M., Moran, V. E., Azpilicueta, A. E., & Piccolo, N. V. (2019). Alternate Forms Public Domain RIASEC Markers for Interests and Self-Efficacy: Spanish version. Electronic Journal of Research in Educational Psychology, 17(2), 359-382.",
+    "reference_doi": "10.25115/ejrep.v17i48.2136",
+    "reference_url": "https://ojs.ual.es/ojs/index.php/EJREP/article/view/2136",
     "license": "Public domain",
     "response_scale": {
       "1": "Muy impreciso",

package/data/mapping.json

@@ -1,8 +1,14 @@
 {
   "meta": {
     "description": "Mapping from Holland RIASEC types to Colombian CINE F 2013 AC broad fields (campo amplio)",
-    "source": "Expert mapping based on Holland (1997) occupational classification and SNIES CINE taxonomy",
-    "note": "Field names match exact values in SNIES program catalog. Weights range 0-1: 1.0 = primary match, 0.5-0.7 = secondary match."
+    "source": "Author-curated weighted mapping based on Holland (1997) classical occupational typology and the SNIES CINE F 2013 AC field taxonomy maintained by Colombia's Ministry of Education.",
+    "note": "Field names match exact values in SNIES program catalog. Weights range 0-1: 1.0 = primary match, 0.5-0.7 = secondary match.",
+    "validation_status": "Not independently psychometrically validated against external criteria such as O*NET RIASEC interest profiles. The mapping is consistent with classical Holland theory, but a more rigorous derivation would require validation studies that are not currently published.",
+    "contribution_invitation": "If you have access to empirically derived RIASEC-to-CINE weights (e.g., from O*NET interest profiles cross-walked via SOC-ISCO-CINE), pull requests are welcome. See github.com/affromero/riasec-co.",
+    "references": [
+      "Holland, J. L. (1997). Making vocational choices: A theory of vocational personalities and work environments (3rd ed.). Psychological Assessment Resources. https://archive.org/details/makingvocational0000holl",
+      "SNIES — Sistema Nacional de Información de la Educación Superior. https://hecaa.mineducacion.gov.co/consultaspublicas/programas"
+    ]
   },
   "mapping": {
     "R": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "riasec-co",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Bayesian adaptive RIASEC quiz engine with Colombian SNIES program data",
   "type": "module",
   "main": "dist/index.js",
@@ -13,7 +13,8 @@
   },
   "files": [
     "dist/",
-    "data/"
+    "data/",
+    "README.md"
   ],
   "scripts": {
     "prebuild": "rm -rf data && cp -r ../../data/canonical data",