@bradtech/ontologies 1.1.0

package/src/extractor.ts

@@ -0,0 +1,207 @@
+/**
+ * Extractor & Open Data Publisher for @bradtech/ontologies.
+ */
+
+import type { OntologyCatalogIndex } from './loader'
+import type {
+   AnyOntologyItem,
+   FlatSelectOption,
+   HierarchyNode,
+   OntologyDomain,
+   OntologyLookupResult,
+   SupportedLanguage,
+} from './types'
+
+/**
+ * Returns localized label for an ontology item given a target language with fallback.
+ */
+export function getLocalizedLabel(
+   item: AnyOntologyItem,
+   language: SupportedLanguage = 'fr',
+): string {
+   if (item.translations && item.translations[language]) {
+      return item.translations[language]!
+   }
+   if (item.translations && item.translations.fr) {
+      return item.translations.fr!
+   }
+   if (item.translations && item.translations.en) {
+      return item.translations.en!
+   }
+   return item.title
+}
+
+/**
+ * Extracts a flat list of options for a domain, localized to the specified language.
+ * Ideal for rendering dropdown select components (UI/API).
+ */
+export function extractFlatList(
+   catalog: OntologyCatalogIndex,
+   domain: OntologyDomain,
+   language: SupportedLanguage = 'fr',
+): FlatSelectOption[] {
+   const items = catalog.byDomain.get(domain) || []
+   return items.map((item) => ({
+      id: item.id,
+      label: getLocalizedLabel(item, language),
+      description: item.description,
+      standards: item.standards,
+   }))
+}
+
+/**
+ * Extracts a key-value dictionary { id: label } for direct consumption by UI form definitions.
+ */
+export function extractFlatMap(
+   catalog: OntologyCatalogIndex,
+   domain: OntologyDomain,
+   language: SupportedLanguage = 'fr',
+): Record<string, string> {
+   const list = extractFlatList(catalog, domain, language)
+   const map: Record<string, string> = {}
+   for (const opt of list) {
+      map[opt.id] = opt.label
+   }
+   return map
+}
+
+/**
+ * Extracts a hierarchical taxonomy tree for cascading selectors.
+ */
+export function extractHierarchy(
+   catalog: OntologyCatalogIndex,
+   domain: OntologyDomain,
+   _language: SupportedLanguage = 'fr',
+): HierarchyNode[] {
+   const items = catalog.byDomain.get(domain) || []
+
+   // If items have category or hierarchy grouping (e.g. crops by category)
+   const categoryGroups = new Map<string, AnyOntologyItem[]>()
+
+   for (const item of items) {
+      const category = (item as any).category || 'general'
+      if (!categoryGroups.has(category)) {
+         categoryGroups.set(category, [])
+      }
+      categoryGroups.get(category)!.push(item)
+   }
+
+   const roots: HierarchyNode[] = []
+
+   for (const [category, childrenItems] of categoryGroups.entries()) {
+      const childrenNodes: HierarchyNode[] = childrenItems.map((child) => ({
+         item: child,
+         children: [],
+      }))
+
+      roots.push({
+         item: {
+            type: 'category',
+            id: category,
+            title: category.toUpperCase(),
+            description: `Category: ${category}`,
+            tags: [domain, category],
+            translations: { fr: category, en: category },
+         },
+         children: childrenNodes,
+      })
+   }
+
+   return roots
+}
+
+/**
+ * Universal lookup that resolves any input (ID, EPPO code, TelePAC code, AGROVOC URI, or title).
+ */
+export function lookup(
+   catalog: OntologyCatalogIndex,
+   query: string,
+): OntologyLookupResult | null {
+   if (!query || typeof query !== 'string') return null
+   const trimmed = query.trim()
+   const upper = trimmed.toUpperCase()
+
+   // 1. Exact ID match
+   if (catalog.byId.has(trimmed)) {
+      const item = catalog.byId.get(trimmed)!
+      return { item, domain: resolveDomainOfItem(item), matchedBy: 'id' }
+   }
+
+   // 2. EPPO code match
+   if (catalog.byEppo.has(upper)) {
+      const item = catalog.byEppo.get(upper)!
+      return { item, domain: 'crops', matchedBy: 'eppo' }
+   }
+
+   // 3. TelePAC RPG code match
+   if (catalog.byTelepac.has(upper)) {
+      const item = catalog.byTelepac.get(upper)!
+      return { item, domain: 'crops', matchedBy: 'telepac' }
+   }
+
+   // 4. AGROVOC URI/Code match
+   if (catalog.byAgrovoc.has(trimmed)) {
+      const item = catalog.byAgrovoc.get(trimmed)!
+      return { item, domain: resolveDomainOfItem(item), matchedBy: 'agrovoc' }
+   }
+
+   // 5. Case-insensitive title / alias scan
+   for (const item of catalog.items) {
+      if (item.title.toLowerCase() === trimmed.toLowerCase()) {
+         return { item, domain: resolveDomainOfItem(item), matchedBy: 'alias' }
+      }
+      for (const trans of Object.values(item.translations || {})) {
+         if (trans && trans.toLowerCase() === trimmed.toLowerCase()) {
+            return { item, domain: resolveDomainOfItem(item), matchedBy: 'alias' }
+         }
+      }
+   }
+
+   return null
+}
+
+function resolveDomainOfItem(item: AnyOntologyItem): OntologyDomain {
+   if (item.type === 'soil') return 'soils'
+   if (item.type === 'irrigation') return 'irrigations'
+   if (item.type === 'crop') return 'crops'
+   return 'crop-covers'
+}
+
+/**
+ * Converts ontology items into an Open Data Schema.org / DCAT-AP compliant JSON-LD graph.
+ */
+export function toOpenDataJsonLd(
+   catalog: OntologyCatalogIndex,
+   domain?: OntologyDomain,
+): Record<string, any> {
+   const targetItems = domain ? catalog.byDomain.get(domain) || [] : catalog.items
+
+   return {
+      '@context': {
+         '@vocab': 'https://schema.org/',
+         'okf': 'https://openknowledgeformat.org/ns/',
+         'eppo': 'https://gd.eppo.int/taxon/',
+         'agrovoc': 'http://aims.fao.org/aos/agrovoc/',
+         'wrb': 'https://www.isric.org/explore/wrb/',
+      },
+      '@type': 'DataCatalog',
+      'name': 'OSFARM & Brad Agricultural Taxonomies',
+      'url': 'https://lexicon.osfarm.org',
+      'publisher': {
+         '@type': 'Organization',
+         'name': 'Brad Technology SAS & OSFARM Collective',
+      },
+      'itemListElement': targetItems.map((item) => ({
+         '@type': item.type === 'crop' ? 'Plant' : 'DefinedTerm',
+         '@id': `okf:${item.type}/${item.id}`,
+         'identifier': item.id,
+         'name': item.title,
+         'description': item.description,
+         'keywords': item.tags.join(', '),
+         'sameAs': [
+            item.standards?.eppo ? `https://gd.eppo.int/taxon/${item.standards.eppo}` : null,
+            item.standards?.agrovoc ? `http://aims.fao.org/aos/agrovoc/${item.standards.agrovoc}` : null,
+         ].filter(Boolean),
+      })),
+   }
+}

package/src/index.ts

@@ -0,0 +1,98 @@
+/**
+ * @bradtech/ontologies
+ * Open Knowledge Format (OKF v0.1) Agricultural Lexicon & Taxonomies
+ */
+
+import { EMBEDDED_ONTOLOGY_ITEMS } from './embeddedData'
+import { indexOntologyItems, type OntologyCatalogIndex } from './loader'
+import {
+   extractFlatList,
+   extractFlatMap,
+   extractHierarchy,
+   getLocalizedLabel,
+   lookup,
+   toOpenDataJsonLd,
+} from './extractor'
+import type {
+   AnyOntologyItem,
+   CropAgronomy,
+   CropCoverEffects,
+   CropCoverOntologyItem,
+   CropOntologyItem,
+   FlatSelectOption,
+   HierarchyNode,
+   IrrigationEngineering,
+   IrrigationOntologyItem,
+   LanguageMap,
+   OntologyDomain,
+   OntologyLookupResult,
+   OntologyStandards,
+   SoilOntologyItem,
+   SoilPhysics,
+   SupportedLanguage,
+} from './types'
+
+export type {
+   AnyOntologyItem,
+   CropAgronomy,
+   CropCoverEffects,
+   CropCoverOntologyItem,
+   CropOntologyItem,
+   FlatSelectOption,
+   HierarchyNode,
+   IrrigationEngineering,
+   IrrigationOntologyItem,
+   LanguageMap,
+   OntologyDomain,
+   OntologyLookupResult,
+   OntologyStandards,
+   SoilOntologyItem,
+   SoilPhysics,
+   SupportedLanguage,
+   OntologyCatalogIndex,
+}
+
+export * from './parser'
+export * from './loader'
+export * from './extractor'
+export { EMBEDDED_ONTOLOGY_ITEMS } from './embeddedData'
+
+/**
+ * Singleton instance of the built-in Agricultural Ontology Catalog.
+ * Lazily loaded on first access using statically embedded concepts (zero fs dependency).
+ */
+let _defaultCatalog: OntologyCatalogIndex | null = null
+
+export function getDefaultCatalog(): OntologyCatalogIndex {
+   if (!_defaultCatalog) {
+      _defaultCatalog = indexOntologyItems(EMBEDDED_ONTOLOGY_ITEMS)
+   }
+   return _defaultCatalog
+}
+
+/**
+ * Convenience helper methods using the default built-in catalog.
+ */
+export const Lexicon = {
+   getCatalog: getDefaultCatalog,
+
+   getFlatList(domain: OntologyDomain, lang: SupportedLanguage = 'fr'): FlatSelectOption[] {
+      return extractFlatList(getDefaultCatalog(), domain, lang)
+   },
+
+   getFlatMap(domain: OntologyDomain, lang: SupportedLanguage = 'fr'): Record<string, string> {
+      return extractFlatMap(getDefaultCatalog(), domain, lang)
+   },
+
+   getHierarchy(domain: OntologyDomain, lang: SupportedLanguage = 'fr'): HierarchyNode[] {
+      return extractHierarchy(getDefaultCatalog(), domain, lang)
+   },
+
+   lookup(query: string): OntologyLookupResult | null {
+      return lookup(getDefaultCatalog(), query)
+   },
+
+   toOpenData(domain?: OntologyDomain): Record<string, any> {
+      return toOpenDataJsonLd(getDefaultCatalog(), domain)
+   },
+}

package/src/loader.ts

@@ -0,0 +1,126 @@
+/**
+ * OKF Knowledge Graph & Directory Loader for @bradtech/ontologies.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { parseOkfDocument } from './parser'
+import type {
+   AnyOntologyItem,
+   CropOntologyItem,
+   IrrigationOntologyItem,
+   OntologyDomain,
+   SoilOntologyItem,
+} from './types'
+
+export interface OntologyCatalogIndex {
+   items: AnyOntologyItem[]
+   byId: Map<string, AnyOntologyItem>
+   byDomain: Map<OntologyDomain, AnyOntologyItem[]>
+   byEppo: Map<string, CropOntologyItem>
+   byAgrovoc: Map<string, AnyOntologyItem>
+   byTelepac: Map<string, CropOntologyItem>
+}
+
+/**
+ * Builds an in-memory index from a list of parsed ontology items.
+ */
+export function indexOntologyItems(rawItems: AnyOntologyItem[]): OntologyCatalogIndex {
+   const items: AnyOntologyItem[] = []
+   const byId = new Map<string, AnyOntologyItem>()
+   const byDomain = new Map<OntologyDomain, AnyOntologyItem[]>([
+      ['soils', []],
+      ['irrigations', []],
+      ['crops', []],
+      ['crop-covers', []],
+   ])
+   const byEppo = new Map<string, CropOntologyItem>()
+   const byAgrovoc = new Map<string, AnyOntologyItem>()
+   const byTelepac = new Map<string, CropOntologyItem>()
+
+   for (const doc of rawItems) {
+      if (doc.type === 'catalog' || doc.type === 'domain') {
+         byId.set(doc.id, doc)
+         continue
+      }
+
+      items.push(doc)
+      byId.set(doc.id, doc)
+
+      if (doc.type === 'soil') {
+         byDomain.get('soils')?.push(doc as SoilOntologyItem)
+      } else if (doc.type === 'irrigation') {
+         byDomain.get('irrigations')?.push(doc as IrrigationOntologyItem)
+      } else if (doc.type === 'crop') {
+         byDomain.get('crops')?.push(doc as CropOntologyItem)
+      } else if (doc.type === 'crop-cover') {
+         byDomain.get('crop-covers')?.push(doc)
+      }
+
+      if (doc.standards?.eppo && doc.type === 'crop') {
+         byEppo.set(doc.standards.eppo.toUpperCase(), doc as CropOntologyItem)
+      }
+      if (doc.standards?.agrovoc) {
+         byAgrovoc.set(String(doc.standards.agrovoc), doc)
+      }
+      if (doc.standards?.telepac_rpg && Array.isArray(doc.standards.telepac_rpg)) {
+         for (const code of doc.standards.telepac_rpg) {
+            byTelepac.set(String(code).toUpperCase(), doc as CropOntologyItem)
+         }
+      }
+   }
+
+   return {
+      items,
+      byId,
+      byDomain,
+      byEppo,
+      byAgrovoc,
+      byTelepac,
+   }
+}
+
+/**
+ * Recursively scans a directory and returns all .md file paths.
+ */
+export function scanMarkdownFiles(dirPath: string): string[] {
+   const results: string[] = []
+
+   function walk(current: string) {
+      const entries = readdirSync(current)
+      for (const entry of entries) {
+         if (entry.startsWith('.')) continue
+         const fullPath = join(current, entry)
+         const stat = statSync(fullPath)
+         if (stat.isDirectory()) {
+            walk(fullPath)
+         } else if (stat.isFile() && entry.endsWith('.md')) {
+            results.push(fullPath)
+         }
+      }
+   }
+
+   walk(dirPath)
+   return results
+}
+
+/**
+ * Loads and indexes all OKF documents from the specified directory.
+ */
+export function loadOntologyCatalog(dataPath: string): OntologyCatalogIndex {
+   const targetDir = resolve(dataPath)
+   const files = scanMarkdownFiles(targetDir)
+   const rawItems: AnyOntologyItem[] = []
+
+   for (const filePath of files) {
+      const content = readFileSync(filePath, 'utf-8')
+      try {
+         const doc = parseOkfDocument(content)
+         rawItems.push(doc)
+      } catch (err) {
+         // Skip files without valid frontmatter
+      }
+   }
+
+   return indexOntologyItems(rawItems)
+}

package/src/parser.ts

@@ -0,0 +1,137 @@
+/**
+ * Lightweight, zero-dependency OKF (Open Knowledge Format v0.1) Markdown & YAML parser.
+ */
+
+import type { AnyOntologyItem, BaseOntologyItem } from './types'
+
+/**
+ * Parses simple YAML frontmatter strings into a JavaScript object.
+ * Supports strings, numbers, booleans, flat arrays `[a, b]`, and 1-level nested maps.
+ */
+export function parseYamlFrontmatter(yamlContent: string): Record<string, any> {
+   const result: Record<string, any> = {}
+   const lines = yamlContent.split(/\r?\n/)
+   let currentParentKey: string | null = null
+
+   for (let i = 0; i < lines.length; i++) {
+      const rawLine = lines[i]
+      const trimmed = rawLine.trim()
+
+      if (!trimmed || trimmed.startsWith('#')) {
+         continue
+      }
+
+      // Check indentation to determine if child of current parent
+      const isIndented = /^\s{2,}/.test(rawLine)
+
+      if (isIndented && currentParentKey) {
+         const colonIndex = trimmed.indexOf(':')
+         if (colonIndex !== -1) {
+            const subKey = trimmed.slice(0, colonIndex).trim()
+            const rawVal = trimmed.slice(colonIndex + 1).trim()
+            if (!result[currentParentKey] || typeof result[currentParentKey] !== 'object') {
+               result[currentParentKey] = {}
+            }
+            result[currentParentKey][subKey] = parseYamlValue(rawVal)
+         } else if (trimmed.startsWith('- ')) {
+            // Array element under parent
+            if (!Array.isArray(result[currentParentKey])) {
+               result[currentParentKey] = []
+            }
+            result[currentParentKey].push(parseYamlValue(trimmed.slice(2).trim()))
+         }
+         continue
+      }
+
+      // Top-level key
+      const colonIndex = trimmed.indexOf(':')
+      if (colonIndex === -1) {
+         continue
+      }
+
+      const key = trimmed.slice(0, colonIndex).trim()
+      const rawValue = trimmed.slice(colonIndex + 1).trim()
+
+      if (rawValue === '') {
+         // Parent block starting
+         currentParentKey = key
+         result[key] = {}
+      } else {
+         currentParentKey = null
+         result[key] = parseYamlValue(rawValue)
+      }
+   }
+
+   return result
+}
+
+function parseYamlValue(val: string): any {
+   if (val === '') return null
+   if (val === 'true' || val === 'yes') return true
+   if (val === 'false' || val === 'no') return false
+   if (val === 'null' || val === '~') return null
+
+   // Numbers
+   if (!isNaN(Number(val)) && !val.includes(' ') && val !== '') {
+      return Number(val)
+   }
+
+   // Arrays format: [a, b, c]
+   if (val.startsWith('[') && val.endsWith(']')) {
+      const inner = val.slice(1, -1).trim()
+      if (!inner) return []
+      return inner
+         .split(',')
+         .map((item) => item.trim())
+         .map((item) => {
+            if (item.startsWith('"') && item.endsWith('"')) return item.slice(1, -1)
+            if (item.startsWith("'") && item.endsWith("'")) return item.slice(1, -1)
+            return parseYamlValue(item)
+         })
+   }
+
+   // Strip surrounding quotes
+   if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      return val.slice(1, -1)
+   }
+
+   return val
+}
+
+/**
+ * Parses an entire OKF Markdown file into an OntologyItem.
+ */
+export function parseOkfDocument(content: string): AnyOntologyItem {
+   const trimmed = content.trim()
+
+   if (!trimmed.startsWith('---')) {
+      throw new Error('Invalid OKF document: Missing leading YAML frontmatter delimiter (---)')
+   }
+
+   const secondDelimiterIndex = trimmed.indexOf('\n---', 3)
+   if (secondDelimiterIndex === -1) {
+      throw new Error('Invalid OKF document: Missing closing YAML frontmatter delimiter (---)')
+   }
+
+   const frontmatterRaw = trimmed.slice(3, secondDelimiterIndex).trim()
+   const bodyMarkdown = trimmed.slice(secondDelimiterIndex + 4).trim()
+
+   const frontmatter = parseYamlFrontmatter(frontmatterRaw)
+
+   if (!frontmatter.id || !frontmatter.title) {
+      throw new Error(`Invalid OKF document: Mandatory "id" or "title" missing in frontmatter`)
+   }
+
+   return {
+      type: frontmatter.type || 'concept',
+      id: String(frontmatter.id),
+      title: String(frontmatter.title),
+      description: String(frontmatter.description || ''),
+      tags: Array.isArray(frontmatter.tags) ? frontmatter.tags : [],
+      translations: frontmatter.translations || {},
+      standards: frontmatter.standards || {},
+      bodyMarkdown,
+      timestamp: frontmatter.timestamp,
+      ...frontmatter,
+   } as AnyOntologyItem
+}

package/src/types.ts

@@ -0,0 +1,110 @@
+/**
+ * Core type definitions for @bradtech/ontologies (OKF v0.1 Agricultural Lexicon)
+ */
+
+export type SupportedLanguage = 'fr' | 'en' | 'es' | 'it' | 'de'
+
+export type LanguageMap = Partial<Record<SupportedLanguage, string>>
+
+export type OntologyDomain = 'soils' | 'irrigations' | 'crops' | 'crop-covers'
+
+export interface OntologyStandards {
+   eppo?: string
+   agrovoc?: string
+   inrae?: string
+   usda?: string
+   wrb?: string
+   icid?: string
+   telepac_rpg?: string[]
+   [key: string]: unknown
+}
+
+export interface BaseOntologyItem {
+   type: string
+   id: string
+   title: string
+   description: string
+   tags: string[]
+   translations: LanguageMap
+   standards?: OntologyStandards
+   bodyMarkdown?: string
+   timestamp?: string
+}
+
+export interface SoilPhysics {
+   fieldCapacityPoint: number // % Volumetric Soil Moisture (Capacité au champ)
+   temporaryWiltingPoint: number // % Volumetric Soil Moisture (Point de stress)
+   permanentWiltingPoint: number // % Volumetric Soil Moisture (Point de flétrissement permanent)
+   bulkDensityKgM3: number // kg/m³
+   clayPercentageApprox?: number
+   sandPercentageApprox?: number
+   siltPercentageApprox?: number
+}
+
+export interface SoilOntologyItem extends BaseOntologyItem {
+   type: 'soil'
+   physics: SoilPhysics
+}
+
+export interface IrrigationEngineering {
+   method: string
+   applicationEfficiency: number // e.g. 0.90 for drip, 0.75 for sprinkler
+   wettingPatternFraction: number // fraction of soil surface wetted (0.2 to 1.0)
+}
+
+export interface IrrigationOntologyItem extends BaseOntologyItem {
+   type: 'irrigation'
+   engineering: IrrigationEngineering
+}
+
+export interface CropAgronomy {
+   rootDepthMaxCm: number
+   kcInitial: number
+   kcMid: number
+   kcEnd: number
+   baseTemperatureGdd: number // Base temperature for Growing Degree Days (°C)
+   waterRequirementMmAnnual?: number
+}
+
+export interface CropOntologyItem extends BaseOntologyItem {
+   type: 'crop'
+   category: string // e.g. 'viticulture', 'aromatics', 'arboriculture', 'cereals'
+   scientificName?: string
+   agronomy: CropAgronomy
+}
+
+export interface CropCoverEffects {
+   soilProtectionFactor: number // 0.0 to 1.0
+   waterCompetitionIndex: number // 0.0 (negligible) to 1.0 (high competition)
+   nitrogenFixation: boolean
+}
+
+export interface CropCoverOntologyItem extends BaseOntologyItem {
+   type: 'crop-cover'
+   effects: CropCoverEffects
+}
+
+export type AnyOntologyItem =
+   | SoilOntologyItem
+   | IrrigationOntologyItem
+   | CropOntologyItem
+   | CropCoverOntologyItem
+   | BaseOntologyItem
+
+export interface FlatSelectOption {
+   id: string
+   label: string
+   description?: string
+   standards?: OntologyStandards
+}
+
+export interface HierarchyNode<T = AnyOntologyItem> {
+   item: T
+   children: HierarchyNode<T>[]
+}
+
+export interface OntologyLookupResult {
+   item: AnyOntologyItem
+   domain: OntologyDomain
+   matchedBy: 'id' | 'eppo' | 'agrovoc' | 'telepac' | 'alias'
+}