soka 0.0.1.beta2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 78ad837d61ec2a941c9e10af5aca993ef92b47db056e60be35a37b01a79e1e73
+  data.tar.gz: 6c0c38931ad663decc2e18cad777a3decb1dc0bb32815db4289e2d5e60eec747
+SHA512:
+  metadata.gz: 0babc9b4e2d5cd704e14c31bb955dea922133f844e78596f9fff25a0cd8c4ad5601248c276342d8adc0faaaf1e061129cad12283830878dfb72165df248efca1
+  data.tar.gz: e6b33ed72f5258dd19a1b62dadb7ec683141e12d64193753e619c94cb2816e16963cfb80322717c161c8bdef0dbd1854cbe82ed2f1e5f956bfc272fa345e0cbf

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,365 @@
+# Omakase Ruby styling for Rails
+# inherit_gem: { rubocop-rails-omakase: rubocop.yml }
+
+# Overwrite or add rules to create your own house style
+#
+# # Use `[a, [b, c]]` not `[ a, [ b, c ] ]`
+# Layout/SpaceInsideArrayLiteralBrackets:
+#   Enabled: false
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.4
+  SuggestExtensions: false
+
+  Exclude:
+    - 'examples/**/*'
+    - 'vendor/**/*'
+
+Gemspec/AddRuntimeDependency: # new in 1.65
+  Enabled: true
+Gemspec/DeprecatedAttributeAssignment: # new in 1.30
+  Enabled: true
+Gemspec/DevelopmentDependencies: # new in 1.44
+  Enabled: true
+Gemspec/RequireMFA: # new in 1.23
+  Enabled: true
+Layout/LineContinuationLeadingSpace: # new in 1.31
+  Enabled: true
+Layout/LineContinuationSpacing: # new in 1.31
+  Enabled: true
+Layout/LineEndStringConcatenationIndentation: # new in 1.18
+  Enabled: true
+Layout/SpaceBeforeBrackets: # new in 1.7
+  Enabled: true
+Lint/AmbiguousAssignment: # new in 1.7
+  Enabled: true
+Lint/AmbiguousOperatorPrecedence: # new in 1.21
+  Enabled: true
+Lint/AmbiguousRange: # new in 1.19
+  Enabled: true
+Lint/ConstantOverwrittenInRescue: # new in 1.31
+  Enabled: true
+Lint/DeprecatedConstants: # new in 1.8
+  Enabled: true
+Lint/DuplicateBranch: # new in 1.3
+  Enabled: true
+Lint/DuplicateMagicComment: # new in 1.37
+  Enabled: true
+Lint/DuplicateMatchPattern: # new in 1.50
+  Enabled: true
+Lint/DuplicateRegexpCharacterClassElement: # new in 1.1
+  Enabled: true
+Lint/EmptyBlock: # new in 1.1
+  Enabled: true
+Lint/EmptyClass: # new in 1.3
+  Enabled: true
+Lint/EmptyInPattern: # new in 1.16
+  Enabled: true
+Lint/IncompatibleIoSelectWithFiberScheduler: # new in 1.21
+  Enabled: true
+Lint/ItWithoutArgumentsInBlock: # new in 1.59
+  Enabled: true
+Lint/LambdaWithoutLiteralBlock: # new in 1.8
+  Enabled: true
+Lint/LiteralAssignmentInCondition: # new in 1.58
+  Enabled: true
+Lint/MixedCaseRange: # new in 1.53
+  Enabled: true
+Lint/NoReturnInBeginEndBlocks: # new in 1.2
+  Enabled: true
+Lint/NonAtomicFileOperation: # new in 1.31
+  Enabled: true
+Lint/NumberedParameterAssignment: # new in 1.9
+  Enabled: true
+Lint/OrAssignmentToConstant: # new in 1.9
+  Enabled: true
+Lint/RedundantDirGlobSort: # new in 1.8
+  Enabled: true
+Lint/RedundantRegexpQuantifiers: # new in 1.53
+  Enabled: true
+Lint/RefinementImportMethods: # new in 1.27
+  Enabled: true
+Lint/RequireRangeParentheses: # new in 1.32
+  Enabled: true
+Lint/RequireRelativeSelfPath: # new in 1.22
+  Enabled: true
+Lint/SymbolConversion: # new in 1.9
+  Enabled: true
+Lint/ToEnumArguments: # new in 1.1
+  Enabled: true
+Lint/TripleQuotes: # new in 1.9
+  Enabled: true
+Lint/UnexpectedBlockArity: # new in 1.5
+  Enabled: true
+Lint/UnmodifiedReduceAccumulator: # new in 1.1
+  Enabled: true
+Lint/UselessNumericOperation: # new in 1.66
+  Enabled: true
+Lint/UselessRescue: # new in 1.43
+  Enabled: true
+Lint/UselessRuby2Keywords: # new in 1.23
+  Enabled: true
+Metrics/CollectionLiteralLength: # new in 1.47
+  Enabled: true
+Naming/BlockForwarding: # new in 1.24
+  Enabled: true
+Security/CompoundHash: # new in 1.28
+  Enabled: true
+Security/IoMethods: # new in 1.22
+  Enabled: true
+Style/ArgumentsForwarding: # new in 1.1
+  Enabled: true
+Style/ArrayIntersect: # new in 1.40
+  Enabled: true
+Style/CollectionCompact: # new in 1.2
+  Enabled: true
+Style/ComparableClamp: # new in 1.44
+  Enabled: true
+Style/ConcatArrayLiterals: # new in 1.41
+  Enabled: true
+Style/DataInheritance: # new in 1.49
+  Enabled: true
+Style/DirEmpty: # new in 1.48
+  Enabled: true
+Style/DocumentDynamicEvalDefinition: # new in 1.1
+  Enabled: true
+Style/EmptyHeredoc: # new in 1.32
+  Enabled: true
+Style/EndlessMethod: # new in 1.8
+  Enabled: true
+Style/EnvHome: # new in 1.29
+  Enabled: true
+Style/ExactRegexpMatch: # new in 1.51
+  Enabled: true
+Style/FetchEnvVar: # new in 1.28
+  Enabled: true
+Style/FileEmpty: # new in 1.48
+  Enabled: true
+Style/FileRead: # new in 1.24
+  Enabled: true
+Style/FileWrite: # new in 1.24
+  Enabled: true
+Style/HashConversion: # new in 1.10
+  Enabled: true
+Style/HashExcept: # new in 1.7
+  Enabled: true
+Style/IfWithBooleanLiteralBranches: # new in 1.9
+  Enabled: true
+Style/InPatternThen: # new in 1.16
+  Enabled: true
+Style/MagicCommentFormat: # new in 1.35
+  Enabled: true
+Style/MapCompactWithConditionalBlock: # new in 1.30
+  Enabled: true
+Style/MapIntoArray: # new in 1.63
+  Enabled: true
+Style/MapToHash: # new in 1.24
+  Enabled: true
+Style/MapToSet: # new in 1.42
+  Enabled: true
+Style/MinMaxComparison: # new in 1.42
+  Enabled: true
+Style/MultilineInPatternThen: # new in 1.16
+  Enabled: true
+Style/NegatedIfElseCondition: # new in 1.2
+  Enabled: true
+Style/NestedFileDirname: # new in 1.26
+  Enabled: true
+Style/NilLambda: # new in 1.3
+  Enabled: true
+Style/NumberedParameters: # new in 1.22
+  Enabled: true
+Style/NumberedParametersLimit: # new in 1.22
+  Enabled: true
+Style/ObjectThen: # new in 1.28
+  Enabled: true
+Style/OperatorMethodCall: # new in 1.37
+  Enabled: true
+Style/QuotedSymbols: # new in 1.16
+  Enabled: true
+Style/RedundantArgument: # new in 1.4
+  Enabled: true
+Style/RedundantArrayConstructor: # new in 1.52
+  Enabled: true
+Style/RedundantConstantBase: # new in 1.40
+  Enabled: true
+Style/RedundantCurrentDirectoryInPath: # new in 1.53
+  Enabled: true
+Style/RedundantDoubleSplatHashBraces: # new in 1.41
+  Enabled: true
+Style/RedundantEach: # new in 1.38
+  Enabled: true
+Style/RedundantFilterChain: # new in 1.52
+  Enabled: true
+Style/RedundantHeredocDelimiterQuotes: # new in 1.45
+  Enabled: true
+Style/RedundantInitialize: # new in 1.27
+  Enabled: true
+Style/RedundantInterpolationUnfreeze: # new in 1.66
+  Enabled: true
+Style/RedundantLineContinuation: # new in 1.49
+  Enabled: true
+Style/RedundantRegexpArgument: # new in 1.53
+  Enabled: true
+Style/RedundantRegexpConstructor: # new in 1.52
+  Enabled: true
+Style/RedundantSelfAssignmentBranch: # new in 1.19
+  Enabled: true
+Style/RedundantStringEscape: # new in 1.37
+  Enabled: true
+Style/ReturnNilInPredicateMethodDefinition: # new in 1.53
+  Enabled: true
+Style/SelectByRegexp: # new in 1.22
+  Enabled: true
+Style/SendWithLiteralMethodName: # new in 1.64
+  Enabled: true
+Style/SingleLineDoEndBlock: # new in 1.57
+  Enabled: true
+Style/StringChars: # new in 1.12
+  Enabled: true
+Style/SuperArguments: # new in 1.64
+  Enabled: true
+Style/SuperWithArgsParentheses: # new in 1.58
+  Enabled: true
+Style/SwapValues: # new in 1.1
+  Enabled: true
+Style/YAMLFileRead: # new in 1.53
+  Enabled: true
+Lint/DuplicateSetElement: # new in 1.67
+  Enabled: true
+Lint/UnescapedBracketInRegexp: # new in 1.68
+  Enabled: true
+Style/AmbiguousEndlessMethodDefinition: # new in 1.68
+  Enabled: true
+Style/BitwisePredicate: # new in 1.68
+  Enabled: true
+Style/CombinableDefined: # new in 1.68
+  Enabled: true
+Style/KeywordArgumentsMerging: # new in 1.68
+  Enabled: true
+Style/SafeNavigationChainLength: # new in 1.68
+  Enabled: true
+Lint/HashNewWithKeywordArgumentsAsDefault: # new in 1.69
+  Enabled: true
+Lint/NumericOperationWithConstantResult: # new in 1.69
+  Enabled: true
+Lint/UselessDefined: # new in 1.69
+  Enabled: true
+Style/DigChain: # new in 1.69
+  Enabled: true
+Style/FileNull: # new in 1.69
+  Enabled: true
+Style/FileTouch: # new in 1.69
+  Enabled: true
+Lint/ConstantReassignment: # new in 1.70
+  Enabled: true
+Lint/SharedMutableDefault: # new in 1.70
+  Enabled: true
+Style/ItAssignment: # new in 1.70
+  Enabled: true
+Lint/ArrayLiteralInRegexp: # new in 1.71
+  Enabled: true
+Style/HashSlice: # new in 1.71
+  Enabled: true
+Lint/CopDirectiveSyntax: # new in 1.72
+  Enabled: true
+Lint/RedundantTypeConversion: # new in 1.72
+  Enabled: true
+Lint/SuppressedExceptionInNumberConversion: # new in 1.72
+  Enabled: true
+Lint/UselessConstantScoping: # new in 1.72
+  Enabled: true
+Style/RedundantFormat: # new in 1.72
+  Enabled: true
+Style/ComparableBetween: # new in 1.74
+  Enabled: true
+Style/HashFetchChain: # new in 1.75
+  Enabled: true
+Style/ItBlockParameter: # new in 1.75
+  Enabled: true
+Lint/UselessDefaultValueArgument: # new in 1.76
+  Enabled: true
+Lint/UselessOr: # new in 1.76
+  Enabled: true
+Naming/PredicateMethod: # new in 1.76
+  Enabled: true
+Style/EmptyStringInsideInterpolation: # new in 1.76
+  Enabled: true
+Style/RedundantArrayFlatten: # new in 1.76
+  Enabled: true
+Gemspec/AttributeAssignment: # new in 1.77
+  Enabled: true
+Style/CollectionQuerying: # new in 1.77
+  Enabled: true
+Layout/EmptyLinesAfterModuleInclusion: # new in 1.79
+  Enabled: true
+Style/OpenStructUse: # new in 1.23
+  Enabled: true
+# RSpecRails cops have been moved to a separate gem
+# If you need Rails-specific RSpec cops, add rubocop-rspec_rails to your Gemfile
+RSpec/BeEmpty: # new in 2.20
+  Enabled: true
+RSpec/BeEq: # new in 2.9.0
+  Enabled: true
+RSpec/BeNil: # new in 2.9.0
+  Enabled: true
+RSpec/ChangeByZero: # new in 2.11
+  Enabled: true
+RSpec/ContainExactly: # new in 2.19
+  Enabled: true
+RSpec/DuplicatedMetadata: # new in 2.16
+  Enabled: true
+RSpec/EmptyMetadata: # new in 2.24
+  Enabled: true
+RSpec/EmptyOutput: # new in 2.29
+  Enabled: true
+RSpec/Eq: # new in 2.24
+  Enabled: true
+RSpec/ExcessiveDocstringSpacing: # new in 2.5
+  Enabled: true
+RSpec/ExpectInLet: # new in 2.30
+  Enabled: true
+RSpec/IdenticalEqualityAssertion: # new in 2.4
+  Enabled: true
+RSpec/IndexedLet: # new in 2.20
+  Enabled: true
+RSpec/IsExpectedSpecify: # new in 2.27
+  Enabled: true
+RSpec/MatchArray: # new in 2.19
+  Enabled: true
+RSpec/MetadataStyle: # new in 2.24
+  Enabled: true
+RSpec/NoExpectationExample: # new in 2.13
+  Enabled: true
+RSpec/PendingWithoutReason: # new in 2.16
+  Enabled: true
+RSpec/ReceiveMessages: # new in 2.23
+  Enabled: true
+RSpec/RedundantAround: # new in 2.19
+  Enabled: true
+RSpec/RedundantPredicateMatcher: # new in 2.26
+  Enabled: true
+RSpec/RemoveConst: # new in 2.26
+  Enabled: true
+RSpec/RepeatedSubjectCall: # new in 2.27
+  Enabled: true
+RSpec/SkipBlockInsideExample: # new in 2.19
+  Enabled: true
+RSpec/SortMetadata: # new in 2.14
+  Enabled: true
+RSpec/SpecFilePathFormat: # new in 2.24
+  Enabled: false
+RSpec/SpecFilePathSuffix: # new in 2.24
+  Enabled: true
+RSpec/SubjectDeclaration: # new in 2.5
+  Enabled: true
+RSpec/UndescriptiveLiteralsDescription: # new in 2.29
+  Enabled: true
+RSpec/VerifiedDoubleReference: # new in 2.10.0
+  Enabled: true
+# Capybara and FactoryBot cops have been moved to separate gems
+# If you need them, add rubocop-capybara and rubocop-factory_bot to your Gemfile
+RSpec/IncludeExamples: # new in 3.6
+  Enabled: true

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.1.beta2] - 2025-07-29
+
+### Chores
+- chore: update .gitignore to include new documentation files (e122098)
+
+### Added
+- Initial release of Soka gem
+- Multi-LLM provider support (Gemini Studio, OpenAI, Anthropic)
+- Object-oriented tool system with parameter validation
+- ReAct (Reasoning and Acting) engine implementation
+- Memory and ThoughtsMemory systems for conversation tracking
+- Global and instance-level configuration system
+- Retry mechanism with exponential backoff
+- Test helper utilities
+- Comprehensive documentation and examples
+
+### Features
+- Agent base class with DSL for easy customization
+- Tool registration with conditional loading
+- Before/after action hooks and error handlers
+- Real-time event streaming during agent execution
+- Result objects with detailed execution information

data/CLAUDE.md

@@ -0,0 +1,213 @@
+# Soka - Ruby ReAct Agent Framework
+
+## Project Overview
+
+Soka is a Ruby AI Agent framework based on the ReAct (Reasoning and Acting) pattern. It supports multiple AI providers (Gemini Studio, OpenAI, Anthropic) and provides an object-oriented tool system and intelligent memory management.
+
+## Core Architecture
+
+### Directory Structure
+```
+soka/
+├── lib/
+│   ├── soka.rb                    # Main entry point with Zeitwerk autoloading
+│   └── soka/
+│       ├── agent.rb               # Agent base class with DSL and execution logic
+│       ├── agent_tool.rb          # Tool base class with parameter validation
+│       ├── agent_tools/
+│       │   └── params_validator.rb # Parameter validation module
+│       ├── agents/                # Agent feature modules
+│       │   ├── dsl_methods.rb     # DSL method definitions
+│       │   ├── hook_manager.rb    # Lifecycle hook management
+│       │   ├── llm_builder.rb     # LLM instance construction
+│       │   ├── retry_handler.rb   # Retry mechanism
+│       │   └── tool_builder.rb    # Tool construction and management
+│       ├── configuration.rb       # Global configuration system
+│       ├── llm.rb                 # LLM unified interface layer
+│       ├── llms/                  # LLM provider implementations
+│       │   ├── base.rb           # LLM base class
+│       │   ├── concerns/         # Shared functionality modules
+│       │   │   ├── response_parser.rb    # Response parsing
+│       │   │   └── streaming_handler.rb  # Stream processing
+│       │   ├── gemini.rb         # Google Gemini implementation
+│       │   ├── openai.rb         # OpenAI implementation
+│       │   └── anthropic.rb      # Anthropic implementation
+│       ├── engines/              # Reasoning engines
+│       │   ├── base.rb          # Engine base class
+│       │   ├── concerns/        # Engine shared modules
+│       │   │   ├── prompt_template.rb     # Prompt templates
+│       │   │   └── response_processor.rb  # Response processing
+│       │   ├── react.rb         # ReAct reasoning engine
+│       │   └── reasoning_context.rb # Reasoning context management
+│       ├── memory.rb             # Conversation memory management
+│       ├── thoughts_memory.rb    # Thought process memory
+│       ├── result.rb             # Result object encapsulation
+│       ├── test_helpers.rb       # RSpec test helpers
+│       └── version.rb            # Version definition
+├── examples/
+│   ├── 1_basic.rb               # Basic usage example
+│   ├── 2_event_handling.rb      # Event handling example
+│   ├── 3_memory.rb              # Memory usage example
+│   ├── 4_hooks.rb               # Lifecycle hooks example
+│   ├── 5_error_handling.rb      # Error handling example
+│   ├── 6_retry.rb               # Retry mechanism example
+│   ├── 7_tool_conditional.rb    # Conditional tools example
+│   └── 8_multi_provider.rb      # Multi-provider example
+├── spec/                         # RSpec tests
+└── test_soka.rb                 # Quick test script
+```
+
+## Core Component Descriptions
+
+### 1. Agent System (`agent.rb`)
+- Provides DSL for defining AI settings, tool registration, and retry mechanisms
+- Supports conditional tool loading (`if:` option)
+- Built-in lifecycle hooks (before_action, after_action, on_error)
+- Uses `times` loop instead of `loop` for iteration control
+- Modular design: functionality separated into concern modules
+  - `DSLMethods`: DSL method definitions
+  - `HookManager`: Lifecycle hook management
+  - `LLMBuilder`: LLM instance construction
+  - `RetryHandler`: Retry handling
+  - `ToolBuilder`: Tool construction and management
+
+### 2. Tool System (`agent_tool.rb`)
+- Grape API-like parameter definition system
+- Built-in parameter validation (presence, length, inclusion, format)
+- Supports required and optional parameters
+- Auto-generates tool description schemas
+
+### 3. ReAct Engine (`engines/react.rb`)
+- Implements tagged ReAct flow: `<Thought>`, `<Action>`, `<Observation>`, `<Final_Answer>`
+- Uses Struct instead of OpenStruct (Rubocop compliant)
+- Automatically manages conversation context and tool execution
+- Calculates confidence scores (based on iteration count)
+- Uses `ReasoningContext` to manage reasoning state
+- Shared modules:
+  - `PromptTemplate`: Prompt template management
+  - `ResponseProcessor`: Response processing logic
+
+### 4. LLM Integration
+- **LLM Unified Interface Layer (`llm.rb`)**
+  - Provides unified API interface
+  - Supports streaming and non-streaming modes
+  - Auto-routes to corresponding provider implementation
+- **LLM Provider Implementations (`llms/`)**
+  - Gemini: Uses Google Generative AI API, defaults to `gemini-2.5-flash-lite`
+  - OpenAI: Supports GPT-4 series, includes streaming capabilities
+  - Anthropic: Supports Claude 3 series, handles system prompts
+  - Shared modules:
+    - `ResponseParser`: Unified response parsing
+    - `StreamingHandler`: Stream response handling
+- Built-in error handling and retry mechanisms
+
+### 5. Memory System
+- `Memory`: Manages conversation history
+- `ThoughtsMemory`: Records complete ReAct thought processes
+- Supports initial memory loading
+
+## Design Decisions
+
+### 1. Using Zeitwerk Autoloading
+- Simplifies require management
+- Supports hot reloading (development environment)
+- Automatically handles namespaces
+
+### 2. Dry-rb Ecosystem Integration
+- `dry-validation`: Powerful parameter validation
+- `dry-struct`: Type-safe data structures
+- `dry-types`: Type definitions and coercion
+
+### 3. Configuration System Design
+- Supports global configuration and instance-level overrides
+- Block-style DSL provides intuitive configuration
+- Fallback mechanism ensures service availability
+- Configuration includes AI providers and performance settings
+
+### 4. Error Handling Strategy
+- Layered error class inheritance
+- Tool execution errors don't interrupt entire flow
+- Configurable retry mechanism (exponential backoff)
+
+## Testing Strategy
+
+### Unit Tests
+- Using RSpec 3
+- Provides `TestHelpers` module for mocking AI responses
+- Supports tool mocking and error simulation
+
+### Integration Tests
+- `test_soka.rb`: Quick test without real API keys
+- `examples/1_basic.rb`: Actual API integration test
+
+## Development Guide
+
+### Adding New AI Provider
+1. Create new file in `lib/soka/llms/`
+2. Inherit from `Soka::LLMs::Base`
+3. Implement required methods:
+   - `default_model`
+   - `base_url`
+   - `chat(messages, **params)`
+   - `parse_response(response)`
+4. Add new provider to `LLM#create_provider` method
+
+### Adding New Tools
+1. Inherit from `Soka::AgentTool`
+2. Use `desc` to define description
+3. Use `params` block to define parameters
+4. Implement `call` method
+
+### Custom Engines
+1. Inherit from `Soka::Engines::Base`
+2. Implement `reason(task, &block)` method
+3. Use `emit_event` to send events
+4. Return result object inheriting from Struct
+5. Can use concerns modules to share functionality
+
+## Rubocop Compatibility
+- Complies with Ruby 3.0+ standards
+- Major issues fixed:
+  - Using `Struct` instead of `OpenStruct`
+  - Using `format` instead of `String#%`
+  - Using `times` instead of `loop`
+  - Removed unused MODELS constants
+
+## Performance Considerations
+- Maximum iteration limit (default 10)
+- Request timeout settings (default 30 seconds)
+- Memory usage optimization (lazy loading)
+
+## Security
+- API keys managed through environment variables
+- Input parameter validation
+- Error messages don't leak sensitive information
+- Supports `.env` files (not version controlled)
+- Unified error handling hierarchy
+
+## Future Extensions
+- [ ] Support more LLM providers (Cohere, Hugging Face)
+- [ ] Implement caching mechanism
+- [ ] Support vector database integration
+- [ ] Add more built-in tools
+- [ ] WebSocket support for real-time conversations
+- [ ] Support functional tools (use methods directly as tools)
+
+## Development Standards
+
+### Code Quality Checks
+- **When adjusting code, the final step is to run Rubocop to check if the code complies with rules**
+- **When Rubocop has any issues, fix them until all rules are satisfied**
+- **When adjusting code, the final step is to perform a code review to avoid redundant design and ensure code conciseness**
+  - Check for unnecessary intermediate layers or methods
+  - Confirm parameter passing is direct and clear
+  - Remove duplicate code
+  - Avoid over-abstraction
+
+### Code Documentation
+- **When adjusting code, add comments and documentation to methods**
+  - Use YARD format comments
+  - Include method purpose descriptions
+  - Explain parameter types and purposes
+  - Explain return value types and meanings
+  - For complex logic, add implementation detail explanations

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 陳均均 (jiunjiun)
+
+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.