Skip to content

feat(gooddata-sdk): AI Knowledge folders as a declarative YAML layout - #1981

Draft
Tomkess wants to merge 1 commit into
masterfrom
ptom/ai-knowledge-redesign
Draft

Tomkess wants to merge 1 commit into
masterfrom
ptom/ai-knowledge-redesign

Conversation

@Tomkess

@Tomkess Tomkess commented Nov 21, 2026

Copy link
Copy Markdown
Contributor

Draft, not for review yet. It depends on AI Knowledge API changes that are only on the gdc-nas branch ptom/ai-knowledge-redesign (nested folders, uploads in parts, imports), which are not on master.

What it brings

sdk.catalog_ai_knowledge stores the organization's AI Knowledge as YAML and puts it back:

gooddata_layouts/<org>/ai_knowledge/
  documents.yaml            # documents in no folder
  Contracts/
    folder.yaml             # name, description, purpose, extraction, access
    documents.yaml          # file, title, optional path or source
    files/acme.pdf          # optional local file, referenced by path
    Customers/
      folder.yaml           # extraction: inherit, access: inherit
  • folder.yaml holds what the LLM extracts: model, summary instruction, instruction, labels, and fields (name and instruction), plus access (all, inherit, or {workspaces: [...]}). A subfolder inherits both unless it sets its own.
  • documents.yaml lists documents, never their content. A document can name a local path (uploaded in 8 MiB parts, any size) or an https source (the server imports it).
  • store_declarative_ai_knowledge, load_declarative_ai_knowledge and load_and_put_declarative_ai_knowledge(replace_documents=False, delete_missing=False). Put matches folders by their path of names, creates or updates them, uploads or imports missing documents, and moves documents between folders. Folders are deleted only with delete_missing.
  • Also upload_document, import_document and put_transcript.
  • GoodDataApiClient.request sends authenticated requests to endpoints the generated client does not cover. The AI Knowledge endpoints are not in the metadata OpenAPI spec.

Test plan

  • tests/catalog/unit_tests/test_ai_knowledge_layout.py: 9 tests against an in-memory fake of the API. They cover the tree on disk, inheritance, refusing inheritance at the top level, the first put and an idempotent second put, moving a document, store keeping local paths, delete_missing, and an upload in parts.
  • ruff format, ruff check and ty are clean; tests/sdk and tests/catalog/unit_tests pass (246 tests).
  • Not run against a live backend; there are no VCR cassettes yet.

🤖 Generated with Claude Code

catalog_ai_knowledge stores the organization's AI Knowledge as files:
one directory per folder, nested like the folders, each with
folder.yaml (name, description, purpose, extraction: model, summary
and section instructions, fields, labels; access: all, inherit or
workspaces) and documents.yaml (file name, title, and an optional
local path or https source). Content never goes into the YAML.

load_and_put_declarative_ai_knowledge makes AI Knowledge match the
layout: folders are matched by their path of names and created or
updated, a missing document is uploaded in parts (any size) or
imported by the server, a document in another folder is moved, and
delete_missing removes folders that are no longer listed. A subfolder
inherits extraction and access unless it sets its own.

GoodDataApiClient.request sends authenticated requests to endpoints
the generated client does not cover.

jira: trivial
risk: low
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Nov 21, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@codecov

codecov Bot commented Nov 21, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 88.32891% with 44 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.68%. Comparing base (0e2b94a) to head (4314999).

Files with missing lines Patch % Lines
...k/src/gooddata_sdk/catalog/ai_knowledge/service.py 88.82% 20 Missing ⚠️
...data_sdk/catalog/ai_knowledge/declarative_model.py 90.32% 18 Missing ⚠️
packages/gooddata-sdk/src/gooddata_sdk/client.py 28.57% 5 Missing ⚠️
packages/gooddata-sdk/src/gooddata_sdk/sdk.py 80.00% 1 Missing ⚠️
Additional details and impacted files
@@           Coverage Diff            @@
##           master    #1981    +/-   ##
========================================
  Coverage   87.67%   87.68%            
========================================
  Files         358      360     +2     
  Lines       29039    29416   +377     
========================================
+ Hits        25461    25794   +333     
- Misses       3578     3622    +44     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant