geo-semantic-layer 2.0.2 → 3.0.0-alpha.1

package/README.md

@@ -1,14 +1,13 @@
-# GEO Semantic Layer
+# geo-semantic-layer
 
-Framework-agnostic TypeScript library for Generative Engine Optimization (GEO) and structured data automation.
+> Smart JSON-LD toolkit for Generative Engine Optimization (GEO)
 
-Build type-safe, validated JSON-LD schemas that work in any JavaScript environment: React, Vue, Angular, Svelte, Astro, Next.js, Nuxt, Remix, Node.js, Deno, Bun, edge runtimes, and vanilla JavaScript.
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
-[![npm version](https://badge.fury.io/js/geo-semantic-layer.svg)](https://www.npmjs.com/package/geo-semantic-layer)
-
----
+This is the **complete bundle** package that includes all modules:
+- `@semantic-layer/core` - Schema generators & validators
+- `@semantic-layer/extractor` - Extract structured data from HTML
+- `@semantic-layer/optimizer` - Optimize schemas for LLMs
+- `@semantic-layer/auditor` - Audit sites for schema quality
+- `@semantic-layer/cli` - Command-line tools
 
 ## Installation
 
@@ -16,66 +15,117 @@ Build type-safe, validated JSON-LD schemas that work in any JavaScript environme
 npm install geo-semantic-layer
 ```
 
-No framework-specific packages. No peer dependencies.
-
----
-
 ## Quick Start
 
+### 1️⃣ Generate Your First Schema
+
 ```typescript
 import { generateArticleSchema } from 'geo-semantic-layer';
 
 const schema = generateArticleSchema({
-  headline: 'The Future of GEO in 2026',
-  image: 'https://example.com/article.jpg',
-  author: 'John Doe',
-  datePublished: '2026-01-06',
-  description: 'How AI models consume structured data',
-  publisher: {
-    name: 'My Site',
-    logo: 'https://example.com/logo.png'
+  headline: 'Understanding JSON-LD',
+  author: 'Jane Smith',
+  datePublished: '2026-01-09',
+  description: 'A comprehensive guide to structured data',
+  image: 'https://example.com/image.jpg',
+  articleBody: 'Full article content goes here...',
+});
+```
+
+### 2️⃣ Insert into Your HTML
+
+```html
+<script type="application/ld+json">
+  {
+    "@context": "https://schema.org",
+    "@type": "Article",
+    "headline": "Understanding JSON-LD",
+    ...
   }
+</script>
+```
+
+### 3️⃣ That's it! 🎉
+
+Your site now has structured data that Google and LLMs can understand.
+
+---
+
+## Advanced Features
+
+### Extract Data from HTML
+
+```typescript
+import { extractFromURL } from 'geo-semantic-layer/extractor';
+
+const data = await extractFromURL('https://example.com/article');
+console.log(data.type); // 'Article'
+console.log(data.metadata); // Extracted metadata
+```
+
+### Optimize for LLMs
+
+```typescript
+import { optimizeForLLM } from 'geo-semantic-layer/optimizer';
+
+const optimized = optimizeForLLM(schema, {
+  targetModel: 'gpt-4',
+  aggressiveness: 'medium',
 });
 
-// Insert into your HTML:
-// <script type="application/ld+json">{JSON.stringify(schema)}</script>
+console.log(`Reduced ${optimized.stats.reduction}% tokens`);
+```
+
+### Audit Your Project
+
+```bash
+# Lint and validate all schemas
+npx geo-semantic-layer lint
+
+# Pre-commit validation
+npx geo-semantic-layer validate --strict
+
+# Generate HTML report
+npx geo-semantic-layer report -o audit.html
+```
+
+## Modular Installation
+
+For tree-shaking and smaller bundles, install only what you need:
+
+```bash
+npm install @semantic-layer/core @semantic-layer/optimizer
 ```
 
 ---
 
-## Framework Integration
+## Framework Examples
 
 ### React / Next.js
 
 ```tsx
-import { generateOrganizationSchema } from 'geo-semantic-layer';
+import { generateArticleSchema } from 'geo-semantic-layer';
 
-export default function RootLayout({ children }) {
-  const schema = generateOrganizationSchema({
-    name: 'My Company',
-    url: 'https://example.com',
-    logo: 'https://example.com/logo.png',
-    sameAs: [
-      'https://wikidata.org/wiki/Q123',
-      'https://linkedin.com/company/example'
-    ]
+export default function Article() {
+  const schema = generateArticleSchema({
+    headline: 'My Article',
+    author: 'John Doe',
+    datePublished: '2026-01-09',
   });
 
   return (
-    <html>
-      <head>
-        <script
-          type="application/ld+json"
-          dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
-        />
-      </head>
-      <body>{children}</body>
-    </html>
+    <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
+      />
+      <article>{/* Your content */}</article>
+    </>
   );
 }
 ```
 
-### Vue 3 / Nuxt
+### Vue / Nuxt
 
 ```vue
 <script setup>
@@ -83,15 +133,8 @@ import { generateProductSchema } from 'geo-semantic-layer';
 
 const schema = generateProductSchema({
   name: 'Wireless Headphones',
-  description: 'Premium noise-cancelling headphones',
-  image: 'https://example.com/headphones.jpg',
   brand: 'AudioTech',
-  offers: {
-    price: 299.99,
-    priceCurrency: 'USD',
-    availability: 'InStock',
-    url: 'https://example.com/products/headphones'
-  }
+  offers: { price: 299.99, priceCurrency: 'USD' }
 });
 </script>
 
@@ -102,43 +145,15 @@ const schema = generateProductSchema({
 </template>
 ```
 
-### Svelte / SvelteKit
-
-```svelte
-<script>
-  import { generateFAQSchema } from 'geo-semantic-layer';
-
-  const schema = generateFAQSchema({
-    questions: [
-      {
-        question: 'What is GEO?',
-        answer: 'Generative Engine Optimization for AI search engines.'
-      },
-      {
-        question: 'How does it work?',
-        answer: 'By providing structured data AI models can easily consume.'
-      }
-    ]
-  });
-</script>
-
-<svelte:head>
-  <script type="application/ld+json">{JSON.stringify(schema)}</script>
-</svelte:head>
-```
-
 ### Astro
 
 ```astro
 ---
-import { generateBreadcrumbSchema } from 'geo-semantic-layer';
-
-const schema = generateBreadcrumbSchema({
-  items: [
-    { name: 'Home', url: 'https://example.com' },
-    { name: 'Products', url: 'https://example.com/products' },
-    { name: 'Headphones', url: 'https://example.com/products/headphones' }
-  ]
+import { generateOrganizationSchema } from 'geo-semantic-layer';
+
+const schema = generateOrganizationSchema({
+  name: 'My Company',
+  url: 'https://example.com',
 });
 ---
 
@@ -146,187 +161,35 @@ const schema = generateBreadcrumbSchema({
   <head>
     <script type="application/ld+json" set:html={JSON.stringify(schema)} />
   </head>
-  <body>
-    <slot />
-  </body>
+  <body><slot /></body>
 </html>
 ```
 
-### Angular
-
-```typescript
-import { Component } from '@angular/core';
-import { generateLocalBusinessSchema } from 'geo-semantic-layer';
-
-@Component({
-  selector: 'app-root',
-  template: `
-    <div [innerHTML]="schemaScript"></div>
-  `
-})
-export class AppComponent {
-  schema = generateLocalBusinessSchema({
-    name: 'Coffee Shop Downtown',
-    address: {
-      streetAddress: '123 Main St',
-      addressLocality: 'New York',
-      addressRegion: 'NY',
-      postalCode: '10001',
-      addressCountry: 'US'
-    },
-    geo: {
-      latitude: 40.7128,
-      longitude: -74.0060
-    },
-    telephone: '+1-555-123-4567'
-  });
-
-  get schemaScript() {
-    return `<script type="application/ld+json">${JSON.stringify(this.schema)}</script>`;
-  }
-}
-```
-
-### Node.js / Express
-
-```javascript
-import express from 'express';
-import { generateWebPageSchema } from 'geo-semantic-layer';
-
-const app = express();
-
-app.get('/', (req, res) => {
-  const schema = generateWebPageSchema({
-    name: 'Homepage',
-    description: 'Welcome to our site',
-    url: 'https://example.com'
-  });
-
-  res.send(`
-    <!DOCTYPE html>
-    <html>
-      <head>
-        <script type="application/ld+json">
-          ${JSON.stringify(schema)}
-        </script>
-      </head>
-      <body>
-        <h1>Hello World</h1>
-      </body>
-    </html>
-  `);
-});
-```
-
 ---
 
 ## Available Schemas
 
-| Generator | Description |
-|-----------|-------------|
-| `generateOrganizationSchema()` | Company/business information |
-| `generatePersonSchema()` | Individual person profiles |
-| `generateProductSchema()` | E-commerce products with ratings |
-| `generateArticleSchema()` | Blog posts and articles |
-| `generateFAQSchema()` | Frequently asked questions |
+| Generator | Use Case |
+|-----------|----------|
+| `generateOrganizationSchema()` | Companies, organizations |
+| `generatePersonSchema()` | Personal profiles, authors |
+| `generateProductSchema()` | E-commerce products |
+| `generateArticleSchema()` | Blog posts, articles |
+| `generateFAQSchema()` | FAQ pages |
 | `generateBreadcrumbSchema()` | Navigation breadcrumbs |
 | `generateLocalBusinessSchema()` | Physical business locations |
-| `generateEventSchema()` | Events and conferences |
-| `generateWebPageSchema()` | Individual web pages |
-
----
-
-## Features
-
-### GEO Optimization
-
-Optimize JSON-LD for AI model consumption:
-
-```typescript
-import { generateArticleSchema } from 'geo-semantic-layer';
-
-const schema = generateArticleSchema({
-  headline: 'My Article',
-  author: 'John Doe',
-  datePublished: '2026-01-06',
-  articleBody: 'Very long article content...',
-  geo: {
-    contentDensity: 'high' // Prunes decorative data for LLMs
-  }
-});
-```
-
-### Hallucination Guard
-
-Validates entity links against authoritative sources (Wikidata, LinkedIn) to prevent AI misattribution.
-
-### Content Density Engine
-
-Automatically prunes decorative data to generate high-density JSON-LD optimized for LLM context windows.
-
-### Schema Validation
-
-All schemas validated with Zod:
-
-```typescript
-import { ArticleSchema } from 'geo-semantic-layer/schemas';
-
-try {
-  const validated = ArticleSchema.parse(myData);
-} catch (error) {
-  console.error('Invalid schema:', error);
-}
-```
-
-### TypeScript Types
-
-Full type safety:
-
-```typescript
-import type { Article, Product, Organization } from 'geo-semantic-layer';
-
-const article: Article = {
-  '@context': 'https://schema.org',
-  '@type': 'Article',
-  headline: 'My Article',
-  // TypeScript enforces correct structure
-};
-```
+| `generateEventSchema()` | Events, conferences |
+| `generateWebPageSchema()` | Generic web pages |
 
 ---
 
-## Package Exports
-
-```typescript
-// Main entry - all generators and schemas
-import { generateArticleSchema } from 'geo-semantic-layer';
+## Documentation
 
-// Schemas only
-import { ArticleSchema } from 'geo-semantic-layer/schemas';
-
-// Generators only
-import { generateArticleSchema } from 'geo-semantic-layer/generators';
-
-// GEO Engine only
-import { GeoProcessor } from 'geo-semantic-layer/geo';
-```
-
----
-
-## Contributing
-
-Contributions welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
-
----
+- 📖 [Complete Documentation](https://github.com/bdovenbird/semantic-layer#readme)
+- 🎓 [User Guide](https://github.com/bdovenbird/semantic-layer/blob/main/USER_GUIDE.md)
+- 📚 [API Reference](https://github.com/bdovenbird/semantic-layer/blob/main/docs/API.md)
+- 💡 [Examples](https://github.com/bdovenbird/semantic-layer/tree/main/examples)
 
 ## License
 
-MIT © 2026 Rafael Calderón (BDOvenbird Engineering)
-
----
-
-## Links
-
-- [npm](https://www.npmjs.com/package/geo-semantic-layer)
-- [GitHub](https://github.com/bdovenbird/semantic-layer)
-- [Issues](https://github.com/bdovenbird/semantic-layer/issues)
+MIT © Rafael Calderón (BDOvenbird Engineering)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "geo-semantic-layer",
-  "version": "2.0.2",
-  "description": "Framework-agnostic TypeScript library for Generative Engine Optimization (GEO) and structured data automation. Pure functions for JSON-LD generation.",
+  "version": "3.0.0-alpha.1",
+  "description": "Smart JSON-LD toolkit: Extract structured data from HTML, optimize for LLMs, and audit sites. Complete bundle with CLI and programmatic API.",
   "keywords": [
     "seo",
     "geo",
@@ -18,13 +18,14 @@
     "llm",
     "chatgpt",
     "perplexity",
-    "universal",
-    "zero-dependencies"
+    "llm-optimization",
+    "cli"
   ],
   "homepage": "https://github.com/bdovenbird/semantic-layer#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/bdovenbird/semantic-layer.git"
+    "url": "https://github.com/bdovenbird/semantic-layer.git",
+    "directory": "packages/geo-semantic-layer"
   },
   "license": "MIT",
   "author": "Rafael Calderón (BDOvenbird Engineering)",
@@ -34,59 +35,47 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
-    "./schemas": {
-      "import": "./dist/schemas/index.js",
-      "types": "./dist/schemas/index.d.ts"
+    "./extractor": {
+      "import": "./dist/extractor.js",
+      "types": "./dist/extractor.d.ts"
     },
-    "./generators": {
-      "import": "./dist/generators/index.js",
-      "types": "./dist/generators/index.d.ts"
+    "./optimizer": {
+      "import": "./dist/optimizer.js",
+      "types": "./dist/optimizer.d.ts"
     },
-    "./geo": {
-      "import": "./dist/geo/index.js",
-      "types": "./dist/geo/index.d.ts"
+    "./auditor": {
+      "import": "./dist/auditor.js",
+      "types": "./dist/auditor.d.ts"
     }
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "geo-semantic-layer": "./dist/cli.js"
+  },
   "files": [
     "dist",
     "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
     "clean": "rm -rf dist *.tsbuildinfo",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint --cache --cache-location ./node_modules/.cache/eslint .",
-    "lint:fix": "eslint --cache --cache-location ./node_modules/.cache/eslint . --fix",
-    "format": "prettier --write \"**/*.{ts,md,json}\"",
-    "format:check": "prettier --check \"**/*.{ts,md,json}\"",
-    "prepublishOnly": "npm run build"
+    "test": "echo 'Tests run from individual packages'",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "zod": "^3.22.4"
+    "@semantic-layer/auditor": "workspace:*",
+    "@semantic-layer/cli": "workspace:*",
+    "@semantic-layer/core": "workspace:*",
+    "@semantic-layer/extractor": "workspace:*",
+    "@semantic-layer/optimizer": "workspace:*"
   },
   "devDependencies": {
-    "@types/node": "^20.11.5",
-    "@typescript-eslint/eslint-plugin": "^6.19.0",
-    "@typescript-eslint/parser": "^6.19.0",
-    "@vitest/coverage-v8": "^1.2.1",
-    "@vitest/ui": "^1.2.1",
-    "eslint": "^8.56.0",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-import": "^2.29.1",
-    "prettier": "^3.2.4",
     "tsup": "^8.0.1",
-    "typescript": "^5.7.2",
-    "vite": "^5.0.12",
-    "vitest": "^1.2.1"
+    "typescript": "^5.7.2"
   },
   "publishConfig": {
     "access": "public"

package/CHANGELOG.md

@@ -1,61 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-## [2.0.2] - 2026-01-07
-
-### 🎉 Initial Public Release
-
-First public release of **GEO Semantic Layer** - Framework-agnostic TypeScript library for Generative Engine Optimization (GEO) and structured data automation.
-
-#### ✨ Features
-
-- **Pure Functions** - Framework-agnostic generator functions for all major Schema.org types
-- **Zero Framework Dependencies** - Only Zod for runtime validation
-- **Universal Compatibility** - Works in Node.js, Deno, Bun, browsers, edge runtimes, and any JavaScript environment
-- **Full TypeScript Support** - Complete type safety with TypeScript 5.0+
-- **GEO Optimization** - Built-in features for Generative Engine Optimization:
-  - Hallucination Guard - Entity validation against authoritative sources
-  - Content Density Engine - Automatic optimization for LLM context windows
-- **Multiple Entry Points** - Modular exports for schemas, generators, and GEO engine
-- **Tiny Bundle** - ~10KB gzipped with only Zod as dependency
-
-#### 📦 Available Generators
-
-- `generateOrganizationSchema()` - Company/business information
-- `generatePersonSchema()` - Individual person profiles
-- `generateProductSchema()` - E-commerce products with ratings
-- `generateArticleSchema()` - Blog posts and articles
-- `generateFAQSchema()` - Frequently asked questions
-- `generateBreadcrumbSchema()` - Navigation breadcrumbs
-- `generateLocalBusinessSchema()` - Physical business locations
-- `generateEventSchema()` - Events and conferences
-- `generateWebPageSchema()` - Individual web pages
-
-#### 🎯 Framework Integration
-
-Works seamlessly with:
-- React / Next.js
-- Vue 3 / Nuxt
-- Svelte / SvelteKit
-- Astro
-- Angular
-- Node.js / Express
-- Vanilla JavaScript
-
-#### 📚 Package Structure
-
-```
-geo-semantic-layer/
-├── schemas/      # Zod validation schemas
-├── generators/   # Pure generator functions
-└── geo/          # GEO optimization engine
-```
-
----
-
-## Links
-
-- [npm](https://www.npmjs.com/package/geo-semantic-layer)
-- [GitHub](https://github.com/bdovenbird/semantic-layer)
-- [Issues](https://github.com/bdovenbird/semantic-layer/issues)

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Rafael Calderón (BDOvenbird Engineering)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.