Initial release v0.1.0

Author: SergiiShcherbak

.github/CONTRIBUTOR_AGREEMENT.md

@@ -0,0 +1,60 @@
+# ContextGem contributor agreement
+
+This ContextGem Contributor Agreement (**"CCA"**) is based on the [Oracle Contributor Agreement](http://www.oracle.com/technetwork/oca-405177.pdf). The CCA applies to any contribution that you make to any product or project managed by us (the **"project"**), and sets out the intellectual property rights you grant to us in the contributed materials. The term **"us"** shall mean [Shcherbak AI AS](https://shcherbak.ai). The term **"you"** shall mean the person or entity identified below.
+
+If you agree to be bound by these terms, fill in the information requested below and include the filled-in version with your first pull request, under the folder [`.github/contributors/`](/.github/contributors/). Name your file using your GitHub username followed by the `.md` extension. For instance, if your username is example_user, you would create a file named `.github/contributors/example_user.md`.
+
+Read this agreement carefully before signing. These terms and conditions constitute a binding legal agreement.
+
+## Contributor Agreement
+
+1. The term "contribution" or "contributed materials" means any source code, object code, patch, tool, sample, graphic, specification, manual, documentation, or any other material posted or submitted by you to the project.
+
+2. With respect to any worldwide copyrights, or copyright applications and registrations, in your contribution:
+
+    * you hereby assign to us joint ownership, and to the extent that such assignment is or becomes invalid, ineffective or unenforceable, you hereby grant to us a perpetual, irrevocable, non-exclusive, worldwide, no-charge, royalty-free, unrestricted license to exercise all rights under those copyrights. This includes, at our option, the right to sublicense these same rights to third parties through multiple levels of sublicensees or other licensing arrangements;
+
+    * you agree that each of us can do all things in relation to your contribution as if each of us were the sole owners, and if one of us makes a derivative work of your contribution, the one who makes the derivative work (or has it made) will be the sole owner of that derivative work;
+
+    * you agree that you will not assert any moral rights in your contribution against us, our licensees or transferees;
+
+    * you agree that we may register a copyright in your contribution and exercise all ownership rights associated with it; and
+
+    * you agree that neither of us has any duty to consult with, obtain the consent of, pay or render an accounting to the other for any use or distribution of your contribution.
+
+3. With respect to any patents you own, or that you can license without payment to any third party, you hereby grant to us a perpetual, irrevocable, non-exclusive, worldwide, no-charge, royalty-free license to:
+
+    * make, have made, use, sell, offer to sell, import, and otherwise transfer your contribution in whole or in part, alone or in combination with or included in any product, work or materials arising out of the project to which your contribution was submitted, and
+
+    * at our option, to sublicense these same rights to third parties through multiple levels of sublicensees or other licensing arrangements.
+
+4. Except as set out above, you keep all right, title, and interest in your contribution. The rights that you grant to us under these terms are effective on the date you first submitted a contribution to us, even if your submission took place before the date you sign these terms.
+
+5. You covenant, represent, warrant and agree that:
+
+    * Each contribution that you submit is and shall be an original work of authorship and you can legally grant the rights set out in this CCA;
+
+    * to the best of your knowledge, each contribution will not violate any third party's copyrights, trademarks, patents, or other intellectual property rights; and
+
+    * each contribution shall be in compliance with applicable export control laws and other applicable export and import laws.
+    
+You agree to notify us if you become aware of any circumstance which would make any of the foregoing representations inaccurate in any respect. We may publicly disclose your participation in the project, including the fact that you have signed the CCA.
+
+6. This CCA is governed by the laws of Norway and applicable international law. Any choice of law rules will not apply.
+
+7. Please place an "x" on one of the applicable statement below. Please do NOT mark both statements:
+
+    * [ ] I am signing on behalf of myself as an individual and no other person or entity, including my employer, has or will have rights with respect to my contributions.
+
+    * [ ] I am signing on behalf of my employer or a legal entity and I have the actual authority to contractually bind that entity.
+
+## Contributor Details
+
+| Field                          | Entry                |
+|------------------------------- | -------------------- |
+| Name                           |                      |
+| Company name (if applicable)   |                      |
+| Title or role (if applicable)  |                      |
+| Date                           |                      |
+| GitHub username                |                      |
+| Website (optional)             |                      |

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,36 @@
+---
+name: Bug Report
+about: Create a report to help us improve
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Description
+A clear and concise description of what the bug is.
+
+## Steps to Reproduce
+Steps to reproduce the behavior.
+
+## Expected Behavior
+A clear and concise description of what you expected to happen.
+
+## Actual Behavior
+A clear and concise description of what actually happened.
+
+## Environment
+- OS: [e.g. Windows 11, Ubuntu 24.04]
+- Python version: [e.g. 3.13.2]
+- contextgem version: [e.g. 0.1.0]
+- Any other relevant environment details
+
+## Error Logs
+```
+Paste any error logs or traceback here
+```
+
+## Additional Context
+Add any other context about the problem here.
+
+## Possible Solution
+If you have suggestions on how to fix the issue, please describe them here.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Have a question? Just ask :)
+    url: https://github.com/shcherbak-ai/contextgem/discussions/new/
+    about: For questions or discussions that aren't bugs or feature requests
+  - name: Documentation
+    url: https://contextgem.dev
+    about: Check the documentation for usage information and guides

.github/ISSUE_TEMPLATE/documentation_improvement.md

@@ -0,0 +1,19 @@
+---
+name: Documentation Improvement
+about: Suggest improvements to our documentation
+title: '[DOCS] '
+labels: documentation
+assignees: ''
+---
+
+## What Documentation Needs Improvement?
+Provide links or describe the current documentation that needs to be improved.
+
+## What's Wrong or Missing?
+A clear and concise description of what's wrong with the current documentation or what information is missing.
+
+## Suggested Improvement
+A clear and concise description of how you think the documentation should be improved.
+
+## Additional Context
+Add any other context about the documentation request here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature Request
+about: Suggest an idea for this project
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Problem Statement
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+## Proposed Solution
+A clear and concise description of what you want to happen.
+
+## Alternatives Considered
+A clear and concise description of any alternative solutions or features you've considered.
+
+## Additional Context
+Add any other context, mockups, or examples about the feature request here.
+
+## Implementation Ideas
+If you have ideas about how this could be implemented, please share them here.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,32 @@
+<!--- Provide a general summary of your changes in the title. -->
+
+## Description
+<!--- Use this section to describe your changes. If your changes required
+testing, include information about the testing environment and the tests you
+ran. If your test fixes a bug reported in an issue, don't forget to include the
+issue number. If your PR is still a work in progress, that's totally fine – just
+include a note to let us know. -->
+
+## Related Issues
+<!--- Link to any related issues here using the syntax: Fixes #issue_number or Relates to #issue_number -->
+
+## Types of change
+<!-- What type of change does your PR cover? Is it a bug fix, an enhancement
+or new feature, or a change to the documentation? -->
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation update
+- [ ] Performance improvement
+- [ ] Code cleanup or refactor
+
+## How to Test
+<!--- Please describe how reviewers can test your changes -->
+
+## Checklist
+<!--- Before you submit the PR, go over this checklist and make sure you can
+tick off all the boxes. [] -> [x] -->
+- [ ] I confirm that I have the right to submit this contribution and grant all the rights specified in the Contributor Agreement.
+- [ ] I have read, agreed to, filled in, and included my Contributor Agreement in `.github/contributors/[my-username].md`.
+- [ ] I ran the tests, and all new and existing tests passed.
+- [ ] My changes don't require a change to the documentation, or if they do, I've added all required information. 

.github/contributors/.gitkeep

@@ -0,0 +1,41 @@
+# GitHub Workflows
+
+This directory contains GitHub Actions workflow configurations for continuous integration (CI) of the ContextGem project.
+
+## Available Workflows
+
+### tests (`ci-tests.yml`)
+
+**Features:**
+- Runs on multiple operating systems (Ubuntu, macOS, Windows)
+- Tests across Python versions 3.10, 3.11, 3.12, and 3.13
+- Checks formatting with Black
+- Runs test suite with VCR (recorded API responses)
+- Generates test coverage reports
+
+**Trigger:**
+- Automatically runs on push and pull request events on the main branch
+- Can be triggered manually through the GitHub Actions UI
+
+**Environment Variables:**
+- This workflow uses the following environment variables:
+    - `CONTEXTGEM_OPENAI_API_KEY`: Secret OpenAI API key
+    - `GIST_SECRET`: Secret token to upload coverage results to a gist for badge generation
+
+### Check Contributor Agreement (`contributor-agreement-check.yml`)
+
+This workflow ensures all contributors have signed the Contributor Agreement by checking for properly filled agreement files.
+
+**Features:**
+- Verifies that each contributor has a signed agreement file
+- Ensures agreement files are not empty and contain the contributor's username
+- Prevents deletion of existing contributor agreement files
+- Posts helpful comments on PRs when agreement requirements aren't met
+
+**Trigger:**
+- Automatically runs on all pull request events (opened, synchronized, reopened)
+
+## Running Workflows
+
+- **tests:** These run automatically on push/PR to the main branch
+- **Check Contributor Agreement:** Runs automatically on all PRs

.github/workflows/README.md

@@ -0,0 +1,126 @@
+name: tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+
+  tests-with-vcr:
+
+    strategy:
+      matrix:
+        os: [ "ubuntu-latest", "macos-latest", "windows-latest" ]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    defaults:
+      run:
+        shell: bash
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        id: setup-python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+          installer-parallel: true
+  
+      - name: Load cached pip wheels
+        id: cached-pip-wheels
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pip
+            ~/Library/Caches/pip
+            ~\AppData\Local\pip\Cache
+          key: pip-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
+      
+      - name: Install dependencies
+        run: poetry install --no-interaction --with dev --no-root
+
+      - name: Code formatting checks
+        run: |
+          poetry run black --check contextgem dev tests
+          poetry run isort --check contextgem dev tests
+          poetry check --lock
+
+      - name: Run coverage (with VCR)
+        run: |
+          source $VENV
+          coverage run --source contextgem -m pytest --maxfail=1 --disable-warnings -v
+          coverage report -m
+          coverage xml -o coverage_quick.xml
+
+      - name: Extract coverage
+        id: get_coverage
+        run: |
+          COVERAGE=$(python -c "import xml.etree.ElementTree as ET; print(round(float(ET.parse('coverage_quick.xml').getroot().attrib['line-rate'])*100))")
+          echo "percentage=$COVERAGE" >> $GITHUB_OUTPUT
+          # Determine badge color based on coverage percentage
+          if [ $COVERAGE -ge 80 ]; then
+            echo "color=success" >> $GITHUB_OUTPUT
+          elif [ $COVERAGE -ge 60 ]; then
+            echo "color=yellow" >> $GITHUB_OUTPUT
+          else
+            echo "color=critical" >> $GITHUB_OUTPUT
+          fi
+          
+      - name: Upload coverage artifact
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-data
+          path: |
+            coverage_quick.xml
+          retention-days: 1
+
+  update-badge:
+    needs: tests-with-vcr
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download coverage artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: coverage-data
+          
+      - name: Extract coverage
+        id: get_coverage
+        run: |
+          COVERAGE=$(python -c "import xml.etree.ElementTree as ET; print(round(float(ET.parse('coverage_quick.xml').getroot().attrib['line-rate'])*100))")
+          echo "percentage=$COVERAGE" >> $GITHUB_OUTPUT
+          # Determine badge color based on coverage percentage
+          if [ $COVERAGE -ge 80 ]; then
+            echo "color=success" >> $GITHUB_OUTPUT
+          elif [ $COVERAGE -ge 60 ]; then
+            echo "color=yellow" >> $GITHUB_OUTPUT
+          else
+            echo "color=critical" >> $GITHUB_OUTPUT
+          fi
+          
+      - name: Update coverage badge
+        uses: schneegans/dynamic-badges-action@v1.7.0
+        with:
+          auth: ${{ secrets.GIST_SECRET }}
+          gistID: daaee00e1dfff7a29ca10a922ec3becd
+          filename: coverage.json
+          label: coverage
+          message: ${{ steps.get_coverage.outputs.percentage }}%
+          color: ${{ steps.get_coverage.outputs.color }}
+
+env:
+  CONTEXTGEM_OPENAI_API_KEY: ${{ secrets.CONTEXTGEM_OPENAI_API_KEY }}