SED (Semantic Entities Designs)

SED automatically converts your raw database into an AI-ready semantic layer with intelligent business rules.

SED creates a semantic layer that makes AI understand your business data instantly, with automatic business rule generation for security and compliance.

Overview

SED is a local-first database intelligence layer that bridges the gap between technical database schemas and business understanding. It automatically discovers your database structure, generates semantic mappings, and enforces business rules for AI applications.

What SED Does

1. Semantic Layer Generation

SED analyzes your database schema and creates business-friendly semantic mappings:

{
  "entities": [
    {
      "name": "Customer",
      "description": "A person who can place orders and has an account",
      "databaseTable": "users",
      "attributes": [
        {
          "name": "email",
          "description": "Email address",
          "databaseColumn": "email"
        }
      ]
    }
  ]
}

2. Business Rules Engine

SED automatically generates and enforces business rules:

• PII Protection: Blocks access to sensitive data
• Data Validation: Ensures data quality standards
• Access Control: Role-based permissions
• Metric Definitions: Standardized calculations
• Custom Rules: Add your own business logic

3. Local-First Architecture

• 100% Local Processing: No data leaves your machine
• No API Keys Required: Works offline with pattern matching
• Privacy-First: Your database schema stays private

Quick Start

1. Install SED

Choose your preferred ecosystem:

Node.js / TypeScript:

npm install -g sed-cli

Python:

pip install sedql

Note: Both packages provide the same SED functionality. The Python package includes the full CLI integration.

2. Initialize Everything

npx sedql init

This interactive command will:

• Set up your database connection
• Build your semantic layer
• Generate business rules automatically
• Enable rules by default

Supported Databases:

• PostgreSQL
• MySQL
• SQLite

3. Query Your Data

npx sedql query "show me customer orders from last month"

Use natural language to query your database. SED automatically:

• Translates your request to SQL
• Applies business rules for safety
• Returns results with compliance

4. Manage Business Rules

# List all rules
npx sedql rules --list

# Disable a rule temporarily
npx sedql rules --disable pii-protection

# Add custom rules
npx sedql rules --add custom-rules.json

CLI Commands

Core Commands

• sedql init - Initialize SED with database connection and setup everything
• sedql build - Rebuild semantic layer and business rules
• sedql query <query> - Query database using natural language
• sedql validate - Validate semantic layer and business rules
• sedql status - Show current SED status and configuration

Business Rules Management

• sedql rules --list - List all business rules
• sedql rules --add <file> - Add custom rules from JSON file
• sedql rules --disable <rule-id> - Disable a specific rule
• sedql rules --enable <rule-id> - Enable a specific rule

Export & Import

• sedql export - Export semantic layer and configuration
• sedql import <file> - Import configuration from file

Architecture

Database Support

• PostgreSQL: Full support with schema discovery
• MySQL: Comprehensive table and relationship analysis
• SQLite: Lightweight file-based database support

Core Components

• Connectors: Database-specific connection management
• Semantic Layer: Business entity mapping and discovery
• Business Logic Engine: Automatic rule generation and enforcement
• Security Module: PII detection and access control
• Cache Management: Performance optimization and connection pooling

Security & Privacy

• Local Processing: All analysis happens on your machine
• External Calls Off by Default: Anonymous usage analytics are opt-in via SED_ANALYTICS=true
• Business Rules: Automatic PII protection and data validation
• Environment Variables: Secure credential management
• Input Validation: SQL injection protection

Business Rules Engine

Auto-Generated Rules

SED automatically creates business rules based on your database:

{
  "id": "pii-protection",
  "name": "PII Protection",
  "type": "access_policy",
  "severity": "block",
  "condition": {
    "type": "pattern",
    "pattern": ".*(ssn|password|email).*"
  },
  "action": {
    "type": "deny",
    "message": "Access to PII columns is not allowed"
  }
}

Rule Types

• Access Policy: Control who can access what data
• Data Validation: Enforce data quality standards
• Metric Definitions: Standardize business calculations
• Join Rules: Ensure proper table relationships
• Custom Rules: Your own business logic

Rule Management

# See what rules exist
sedql rules --list

# Filter rules by type
sedql rules --list --type access_policy

# Add custom business hours rule
sedql rules --add business-hours.json

# Disable PII protection temporarily
sedql rules --disable pii-protection

Use Cases

AI Integration

• Provide semantic context to LLMs
• Enable natural language database queries
• Bridge the gap between technical and business terminology

Data Governance

• Automatic PII protection
• Data quality enforcement
• Compliance rule management

Development

• Understand complex database schemas
• Discover business entities and relationships
• Generate semantic layer for applications

Python SDK

SED is also available as a Python package (sedql) that provides the same functionality through a Python interface:

Installation

pip install sedql

Basic Usage

from sedql import SEDClient

# Initialize SED client
sed = SEDClient()

# Initialize with database connection
sed.init()

# Build semantic layer
sed.build()

# Query with natural language
result = sed.query("Show me customers with high revenue")
print(result)

# Query with AI integration
ai_result = sed.query_with_ai({
    "natural_language": "Forecast revenue for Q3 2024",
    "ai_model": "gpt-4",
    "business_context": "Revenue forecasting for Q3 planning"
})

Features

• Full CLI Integration: Access all SED CLI features from Python
• Business Rules Engine: Query validation and governance
• Schema Change Detection: Automatic change monitoring
• Security Validation: Business rule enforcement
• AI Integration Framework: Hooks for your AI providers

For complete Python documentation, see: sedql Python Package

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

git clone https://github.com/holy182/sed-cli.git
cd sed-cli
npm install
npm run build
npm test

Running Tests

npm test
npm run test:security

License

GNU Affero General Public License v3.0 (AGPL-3.0) - see LICENSE file for details.

Important: This software is licensed under the AGPL-3.0 license. If you modify and distribute this software, you must make your source code available under the same license. This ensures that improvements to SED's security and governance capabilities are shared back with the community.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki