fact_db 0.0.1

data/lib/fact_db.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "digest"
+
+require_relative "fact_db/version"
+require_relative "fact_db/errors"
+require_relative "fact_db/config"
+require_relative "fact_db/database"
+
+# Models
+require_relative "fact_db/models/content"
+require_relative "fact_db/models/entity"
+require_relative "fact_db/models/entity_alias"
+require_relative "fact_db/models/fact"
+require_relative "fact_db/models/entity_mention"
+require_relative "fact_db/models/fact_source"
+
+# Temporal queries
+require_relative "fact_db/temporal/query"
+require_relative "fact_db/temporal/timeline"
+
+# Resolution
+require_relative "fact_db/resolution/entity_resolver"
+require_relative "fact_db/resolution/fact_resolver"
+
+# Extractors
+require_relative "fact_db/extractors/base"
+require_relative "fact_db/extractors/manual_extractor"
+require_relative "fact_db/extractors/llm_extractor"
+require_relative "fact_db/extractors/rule_based_extractor"
+
+# LLM Integration
+require_relative "fact_db/llm/adapter"
+
+# Pipeline (concurrent processing)
+require_relative "fact_db/pipeline/extraction_pipeline"
+require_relative "fact_db/pipeline/resolution_pipeline"
+
+# Services
+require_relative "fact_db/services/content_service"
+require_relative "fact_db/services/entity_service"
+require_relative "fact_db/services/fact_service"
+
+module FactDb
+  class Facts
+    attr_reader :config, :content_service, :entity_service, :fact_service,
+                :extraction_pipeline, :resolution_pipeline
+
+    def initialize(config: nil)
+      @config = config || FactDb.config
+      Database.establish_connection!(@config)
+
+      @content_service = Services::ContentService.new(@config)
+      @entity_service = Services::EntityService.new(@config)
+      @fact_service = Services::FactService.new(@config)
+      @extraction_pipeline = Pipeline::ExtractionPipeline.new(@config)
+      @resolution_pipeline = Pipeline::ResolutionPipeline.new(@config)
+    end
+
+    # Ingest raw content into the event clock
+    def ingest(raw_text, type:, captured_at: Time.current, metadata: {}, title: nil, source_uri: nil)
+      @content_service.create(
+        raw_text,
+        type: type,
+        captured_at: captured_at,
+        metadata: metadata,
+        title: title,
+        source_uri: source_uri
+      )
+    end
+
+    # Extract facts from content
+    def extract_facts(content_id, extractor: @config.default_extractor)
+      @fact_service.extract_from_content(content_id, extractor: extractor)
+    end
+
+    # Query facts with temporal and entity filtering
+    def query_facts(topic: nil, at: nil, entity: nil, status: :canonical)
+      @fact_service.query(topic: topic, at: at, entity: entity, status: status)
+    end
+
+    # Resolve a name to an entity
+    def resolve_entity(name, type: nil)
+      @entity_service.resolve(name, type: type)
+    end
+
+    # Build a timeline for an entity
+    def timeline_for(entity_id, from: nil, to: nil)
+      @fact_service.timeline(entity_id: entity_id, from: from, to: to)
+    end
+
+    # Get currently valid facts about an entity
+    def current_facts_for(entity_id)
+      query_facts(entity: entity_id, at: nil, status: :canonical)
+    end
+
+    # Get facts valid at a specific point in time
+    def facts_at(at, entity: nil, topic: nil)
+      query_facts(at: at, entity: entity, topic: topic, status: :canonical)
+    end
+
+    # Batch extract facts from multiple content items
+    #
+    # @param content_ids [Array<Integer>] Content IDs to process
+    # @param extractor [Symbol] Extractor type (:manual, :llm, :rule_based)
+    # @param parallel [Boolean] Whether to use parallel processing
+    # @return [Array<Hash>] Results with extracted facts per content
+    def batch_extract(content_ids, extractor: @config.default_extractor, parallel: true)
+      contents = Models::Content.where(id: content_ids).to_a
+      if parallel
+        @extraction_pipeline.process_parallel(contents, extractor: extractor)
+      else
+        @extraction_pipeline.process(contents, extractor: extractor)
+      end
+    end
+
+    # Batch resolve entity names
+    #
+    # @param names [Array<String>] Entity names to resolve
+    # @param type [Symbol, nil] Entity type filter
+    # @return [Array<Hash>] Resolution results
+    def batch_resolve_entities(names, type: nil)
+      @resolution_pipeline.resolve_entities(names, type: type)
+    end
+
+    # Detect fact conflicts for multiple entities
+    #
+    # @param entity_ids [Array<Integer>] Entity IDs to check
+    # @return [Array<Hash>] Conflict detection results
+    def detect_fact_conflicts(entity_ids)
+      @resolution_pipeline.detect_conflicts(entity_ids)
+    end
+  end
+
+  class << self
+    def new(**options)
+      Facts.new(**options)
+    end
+  end
+end

data/mkdocs.yml

@@ -0,0 +1,198 @@
+# MkDocs Configuration for FactDb Documentation
+site_name: FactDb
+site_description: Temporal fact tracking with entity resolution and audit trails for Ruby
+site_author: Dewayne VanHoozer
+site_url: https://madbomber.github.io/fact_db
+copyright: Copyright © 2025 Dewayne VanHoozer
+
+# Repository information
+repo_name: madbomber/fact_db
+repo_url: https://github.com/madbomber/fact_db
+edit_uri: edit/main/docs/
+
+# Configuration
+theme:
+  name: material
+
+  # Color scheme
+  palette:
+    - scheme: default
+      primary: teal
+      accent: amber
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    - scheme: slate
+      primary: teal
+      accent: amber
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  # Typography
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  # Logo and icon
+  icon:
+    repo: fontawesome/brands/github
+    logo: material/clock-time-four
+
+  # Theme features
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.path
+    - navigation.indexes
+    - navigation.top
+    - navigation.footer
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - search.share
+    - header.autohide
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+    - content.action.edit
+    - content.action.view
+
+# Plugins
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+  - tags
+
+# Extensions
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+      title: On this page
+
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.critic
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: madbomber
+      repo: fact_db
+      normalize_issue_symbols: true
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.snippets:
+      check_paths: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+# Extra CSS
+extra_css:
+  - assets/css/custom.css
+
+# Social media and extra configuration
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/madbomber/fact_db
+      name: FactDb on GitHub
+    - icon: fontawesome/solid/gem
+      link: https://rubygems.org/gems/fact_db
+      name: FactDb on RubyGems
+
+  analytics:
+    feedback:
+      title: Was this page helpful?
+      ratings:
+        - icon: material/emoticon-happy-outline
+          name: This page was helpful
+          data: 1
+          note: Thanks for your feedback!
+        - icon: material/emoticon-sad-outline
+          name: This page could be improved
+          data: 0
+          note: Thanks for your feedback! Help us improve by creating an issue.
+
+# Navigation
+nav:
+  - Home:
+      - Overview: index.md
+      - Concepts: concepts.md
+  - Getting Started:
+      - getting-started/index.md
+      - Installation: getting-started/installation.md
+      - Quick Start: getting-started/quick-start.md
+      - Database Setup: getting-started/database-setup.md
+  - Architecture:
+      - architecture/index.md
+      - Three-Layer Model: architecture/three-layer-model.md
+      - Temporal Facts: architecture/temporal-facts.md
+      - Entity Resolution: architecture/entity-resolution.md
+      - Database Schema: architecture/database-schema.md
+  - Guides:
+      - guides/index.md
+      - Configuration: guides/configuration.md
+      - Ingesting Content: guides/ingesting-content.md
+      - Extracting Facts: guides/extracting-facts.md
+      - LLM Integration: guides/llm-integration.md
+      - Temporal Queries: guides/temporal-queries.md
+      - Entity Management: guides/entity-management.md
+      - Batch Processing: guides/batch-processing.md
+  - API Reference:
+      - api/index.md
+      - Facts: api/facts.md
+      - Models:
+          - api/models/index.md
+          - Content: api/models/content.md
+          - Entity: api/models/entity.md
+          - Fact: api/models/fact.md
+      - Services:
+          - api/services/index.md
+          - ContentService: api/services/content-service.md
+          - EntityService: api/services/entity-service.md
+          - FactService: api/services/fact-service.md
+      - Extractors:
+          - api/extractors/index.md
+          - ManualExtractor: api/extractors/manual.md
+          - LLMExtractor: api/extractors/llm.md
+          - RuleBasedExtractor: api/extractors/rule-based.md
+      - Pipeline:
+          - api/pipeline/index.md
+          - ExtractionPipeline: api/pipeline/extraction.md
+          - ResolutionPipeline: api/pipeline/resolution.md
+  - Examples:
+      - examples/index.md
+      - Basic Usage: examples/basic-usage.md
+      - HR Onboarding: examples/hr-onboarding.md
+      - News Analysis: examples/news-analysis.md

metadata

@@ -0,0 +1,288 @@
+--- !ruby/object:Gem::Specification
+name: fact_db
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Dewayne VanHoozer
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: neighbor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: anyway_config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: chronic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: simple_flow
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: debug_me
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  FactDb implements the Event Clock concept - capturing organizational reasoning
+  through temporal facts with validity periods (valid_at/invalid_at), entity resolution,
+  and audit trails back to source content. Built on PostgreSQL with pgvector support
+  for semantic search.
+email:
+- dvanhoozer@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".envrc"
+- CHANGELOG.md
+- COMMITS.md
+- README.md
+- Rakefile
+- db/migrate/001_enable_extensions.rb
+- db/migrate/002_create_contents.rb
+- db/migrate/003_create_entities.rb
+- db/migrate/004_create_entity_aliases.rb
+- db/migrate/005_create_facts.rb
+- db/migrate/006_create_entity_mentions.rb
+- db/migrate/007_create_fact_sources.rb
+- docs/api/extractors/index.md
+- docs/api/extractors/llm.md
+- docs/api/extractors/manual.md
+- docs/api/extractors/rule-based.md
+- docs/api/facts.md
+- docs/api/index.md
+- docs/api/models/content.md
+- docs/api/models/entity.md
+- docs/api/models/fact.md
+- docs/api/models/index.md
+- docs/api/pipeline/extraction.md
+- docs/api/pipeline/index.md
+- docs/api/pipeline/resolution.md
+- docs/api/services/content-service.md
+- docs/api/services/entity-service.md
+- docs/api/services/fact-service.md
+- docs/api/services/index.md
+- docs/architecture/database-schema.md
+- docs/architecture/entity-resolution.md
+- docs/architecture/index.md
+- docs/architecture/temporal-facts.md
+- docs/architecture/three-layer-model.md
+- docs/assets/css/custom.css
+- docs/assets/fact_db.jpg
+- docs/assets/images/fact_db.jpg
+- docs/concepts.md
+- docs/examples/basic-usage.md
+- docs/examples/hr-onboarding.md
+- docs/examples/index.md
+- docs/examples/news-analysis.md
+- docs/getting-started/database-setup.md
+- docs/getting-started/index.md
+- docs/getting-started/installation.md
+- docs/getting-started/quick-start.md
+- docs/guides/batch-processing.md
+- docs/guides/configuration.md
+- docs/guides/entity-management.md
+- docs/guides/extracting-facts.md
+- docs/guides/index.md
+- docs/guides/ingesting-content.md
+- docs/guides/llm-integration.md
+- docs/guides/temporal-queries.md
+- docs/index.md
+- examples/README.md
+- examples/basic_usage.rb
+- examples/entity_management.rb
+- examples/hr_system.rb
+- examples/rule_based_extraction.rb
+- examples/temporal_queries.rb
+- lib/fact_db.rb
+- lib/fact_db/config.rb
+- lib/fact_db/database.rb
+- lib/fact_db/errors.rb
+- lib/fact_db/extractors/base.rb
+- lib/fact_db/extractors/llm_extractor.rb
+- lib/fact_db/extractors/manual_extractor.rb
+- lib/fact_db/extractors/rule_based_extractor.rb
+- lib/fact_db/llm/adapter.rb
+- lib/fact_db/models/content.rb
+- lib/fact_db/models/entity.rb
+- lib/fact_db/models/entity_alias.rb
+- lib/fact_db/models/entity_mention.rb
+- lib/fact_db/models/fact.rb
+- lib/fact_db/models/fact_source.rb
+- lib/fact_db/pipeline/extraction_pipeline.rb
+- lib/fact_db/pipeline/resolution_pipeline.rb
+- lib/fact_db/resolution/entity_resolver.rb
+- lib/fact_db/resolution/fact_resolver.rb
+- lib/fact_db/services/content_service.rb
+- lib/fact_db/services/entity_service.rb
+- lib/fact_db/services/fact_service.rb
+- lib/fact_db/temporal/query.rb
+- lib/fact_db/temporal/timeline.rb
+- lib/fact_db/version.rb
+- mkdocs.yml
+homepage: https://github.com/MadBomber/fact_db
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/MadBomber/fact_db
+  source_code_uri: https://github.com/MadBomber/fact_db
+  changelog_uri: https://github.com/MadBomber/fact_db/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Temporal fact tracking with entity resolution and audit trails
+test_files: []