Merge pull request #64 from textkernel/match-v2

Add Search & Match V2 Functionality

Author: sovren-jwesson

.github/workflows/build.yml

@@ -5,95 +5,16 @@ on:
     branches:
       - master
 
-jobs:
-  get_docfx_status: #check if the last commit was an auto-generation of docfx by this CI workflow
-    name: get-docfx-status
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v2
-      with:
-        fetch-depth: 10 # important for use of HEAD^2
-    # find the last commit message on the source branch
-    - name: Get last commit message
-      shell: bash
-      run: echo "##[set-output name=commitMsg;]$(git log --format=%B -n 1 HEAD^2)"
-      id: extract_message
-    outputs:
-      # create an output that tells the following jobs whether or not we need to generate docfx
-      generate_docfx: ${{ steps.extract_message.outputs.commitMsg != '--- auto-generation of docfx documentation ---' }}
-
-  generate-docfx:
-    needs: get_docfx_status
-    # only run this if we have not generated docfx in last commit
-    if: ${{ needs.get_docfx_status.outputs.generate_docfx == 'true' }}
-    runs-on: windows-latest
-    steps:
-    - uses: actions/checkout@v2
-    - name: Setup .NET Core
-      uses: actions/setup-dotnet@v4
-      with:
-        dotnet-version: 3.1.x
-    - name: Setup DocFX
-      uses: crazy-max/ghaction-chocolatey@v1
-      with:
-        args: install docfx
-    - name: Install dependencies
-      run: dotnet restore
-      working-directory: src/Textkernel.Tx.SDK
-    # generate the DocFX docs into the /docfx/_site folder
-    - name: DocFX Build
-      working-directory: docfx
-      run: docfx docfx.json
-      continue-on-error: false
-    # upload the generated docs into an artifact that can be used by the job below
-    - name: Upload Artifacts
-      uses: actions/upload-artifact@v4
-      with:
-        name: site-${{ matrix.runs-on }}
-        path: docfx/_site
-  
-  #the github-pages-deploy-action needs to run on ubuntu, so use upload/download artifact to generate on windows and publish on ubuntu
-  publish-docfx:
-    needs: [get_docfx_status, generate-docfx]
-    runs-on: ubuntu-latest
-    if: ${{ needs.get_docfx_status.outputs.generate_docfx == 'true' }}
-    steps:
-    - uses: actions/checkout@v2 #checkout so we can do the git commit
-    # extract the PR source branch name from the env variable where we can use it later
-    - name: Extract branch name
-      shell: bash
-      run: echo "##[set-output name=branch;]$(echo ${GITHUB_HEAD_REF#refs/heads/})"
-      id: extract_branch
-    # download the site files as an artifact
-    - name: Download Artifacts
-      uses: actions/download-artifact@v4
-      with:
-        path: site
-        pattern: site-*
-    # publish the generated docs into the /docs folder on a new commit in this branch
-    - name: Publish DocFX to GitHub Pages
-      uses: JamesIves/github-pages-deploy-action@4.1.4
-      with:
-        branch: ${{ steps.extract_branch.outputs.branch }}
-        folder: site #use the downloaded artifact path here
-        target-folder: docs
-        git-config-name: Continuous Integration
-        git-config-email: devs@sovren.com
-        commit-message: --- auto-generation of docfx documentation ---
-        token: ${{ secrets.DOCFX_CI_TOKEN }}
-
+jobs: 
   build:
-    needs: get_docfx_status
-    # only run this if we have already generated docfx in last commit
-    if: ${{ needs.get_docfx_status.outputs.generate_docfx == 'false' }}
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
     - name: Setup .NET Core
       uses: actions/setup-dotnet@v4
       with:
         dotnet-version: |
-          7.0.x
+          8.0.x
           2.0.x
     - name: Install dependencies
       run: dotnet restore
@@ -103,16 +24,14 @@ jobs:
       working-directory: src/Textkernel.Tx.SDK
 
   unit-tests:
-    needs: get_docfx_status
     runs-on: ubuntu-latest
     # only run this if we have already generated docfx in last commit
-    if: ${{ needs.get_docfx_status.outputs.generate_docfx == 'false' }}
     steps:
     - uses: actions/checkout@v2
     - name: Setup .NET Core
       uses: actions/setup-dotnet@v4
       with:
-        dotnet-version: 7.0.x
+        dotnet-version: 8.0.x
     - name: Create credentials file
       run: 'echo "$CREDENTIALS_FILE" > src/Textkernel.Tx.SDK.Tests/credentials.json'
       shell: bash

.github/workflows/docs-publish.yml

@@ -0,0 +1,59 @@
+name: docs-publish
+
+on:
+  pull_request:
+    types:
+      - closed
+  workflow_dispatch: #add this option in case of a failure and we need to re-run
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    # only run this if we have not generated docfx in last commit
+    if: github.event.pull_request.merged == true
+    runs-on: windows-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Setup .NET Core
+      uses: actions/setup-dotnet@v4
+      with:
+        dotnet-version: 3.1.x
+    - name: Setup DocFX
+      uses: crazy-max/ghaction-chocolatey@v1
+      with:
+        args: install docfx
+    - name: Install dependencies
+      run: dotnet restore
+      working-directory: src/Textkernel.Tx.SDK
+    # generate the DocFX docs into the /docfx/_site folder
+    - name: DocFX Build
+      working-directory: docfx
+      run: docfx docfx.json
+      continue-on-error: false
+    # upload the generated docs into an artifact that can be used by the job below
+    - name: Upload Artifacts
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: docfx/_site
+  deploy:
+    needs: build
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.merged == true
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/nuget-publish.yml

@@ -16,7 +16,7 @@ jobs:
       uses: actions/setup-dotnet@v4
       with:
         dotnet-version: |
-          7.0.x
+          8.0.x
           2.0.x
     - name: Install dependencies
       run: dotnet restore

README.md

@@ -73,40 +73,37 @@ ITxClient client = serviceProvider.GetRequiredService<ITxClient>();
 
 For self-hosted customers, you can create a `DataCenter` object with your custom URL using the constructor provided on that class.
 
+### Using the various `TxClient` services
+The `TxClient` has the following services available, exposed as properties on the `ITxClient` interface:
+- Parser
+- Geocoder
+- Formatter
+- SkillsIntelligence
+- SearchMatchV1
+- SearchMatchV2
+
+Each service exposes certain API functionality via its methods. For example, to parse a resume you would do something like:
+```c#
+ITxClient client;//created or injected however
+var parseResponse = await client.Parser.ParseResume(...);
+```
+
+For the complete list of methods on each service and their method signatures, check out our [DocFX-generated docs][docfx-txclient].
+
 ### Handling errors and the `TxException`
 Every call to any of the methods in the `TxClient` should be wrapped in a `try/catch` block. Any 4xx/5xx level errors will cause a `TxException` to be thrown. Sometimes these are a normal and expected part of the Tx API. For example, if you have a website where users upload resumes, sometimes a user will upload a scanned image as their resume. Textkernel does not process these, and will return a `422 Unprocessable Entity` response which will throw a `TxException`. You should handle any `TxException` in a way that makes sense in your application.
 
 Additionally, there are `TxUsableResumeException` and `TxUsableJobException` which are thrown when some error/issue occurs in the API, but the response still contains a usable resume/job. For example, if you are geocoding while parsing and there is a geocoding error (which happens after parsing is done), the `ParsedResume` might still be usable in your application.
 
-### How to create a Matching UI session
-You may be wondering, "where are the Matching UI endpoints/methods?". We have made the difference between a normal API call (such as `Search`) and its equivalent Matching UI call extremely trivial. See the following example:
-
-```c#
-TxClient client = new TxClient(httpClient, new TxClientSettings
-{
-    AccountId = "12345678",
-    ServiceKey = "abcdefghijklmnopqrstuvwxyz",
-    DataCenter = DataCenter.US
-});
-List<string> indexesToSearch = ...;
-FilterCriteria searchQuery = ...;
-
-SearchResponse searchResponse = await client.Search(indexesToSearch, searchQuery);
-```
-To generate a Matching UI session with the above Search query, you simply need to call the `UI(...)` extension method on the `TxClient` object, pass in any UI settings, and then make the same call as above:
-```c#
-MatchUISettings uiSettings = ...;
-GenerateUIResponse uiResponse = await client.UI(uiSettings).Search(indexesToSearch, searchQuery);
-```
-For every relevant method in the `TxClient`, you can create a Matching UI session for that query by doing the same as above.
 
-[examples]: https://github.com/textkernel/tx-dotnet/tree/master/examples
+[examples]: https://github.com/textkernel/tx-dotnet/tree/master/src/Textkernel.Tx.SDK.Examples
 [portal]: https://cloud.textkernel.com/tx/console
 [api-docs]: https://developer.textkernel.com/tx-platform/v10/overview/
 [dotnet-core-cli-tools]: https://docs.microsoft.com/en-us/dotnet/core/tools/
 [nuget-cli]: https://docs.microsoft.com/en-us/nuget/tools/nuget-exe-cli-reference
 [package-manager-console]: https://docs.microsoft.com/en-us/nuget/tools/package-manager-console
 [docfx-docs]: https://textkernel.github.io/tx-dotnet/sdk/
+[docfx-txclient]: https://textkernel.github.io/tx-dotnet/sdk/Textkernel.Tx.ITxClient.html
 [http-client]: https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpclient
 [http-client-guidelines]: https://learn.microsoft.com/en-us/dotnet/fundamentals/networking/http/httpclient-guidelines
 [http-extensions]: https://www.nuget.org/packages/Microsoft.Extensions.Http