Download and extract the Python Demo package.
The package contains the scripts and configuration used to demonstrate collection management, document processing, inference, and related API operations.
Last updated on
Aug 20, 2026
Run, inspect, and adapt a working Python implementation of common Knowledge Base API workflows.
The Python Demo provides a functional starting point for application development. Use the complete workflow to see collection creation, document processing, and AI inference working together, then explore individual scripts for specific collection and inference operations.
Before you begin
Make sure you have:
- Access to the Knowledge Base API.
- The credentials required to authenticate your application.
- Python 3.7 or later. Python 3.11 or later is recommended.
- A PDF that you can use for the complete demo workflow.
If you haven't configured API access, see Set up Knowledge Base API access.
Download and set up the Python Demo
Create a virtual environment:
python3 -m venv venv
Activate the environment:
- On macOS or Linux:
source venv/bin/activate - On Windows:
venv\Scripts\activate
Install the dependencies:
pip install --upgrade pip
pip install -e .
Add the required API credentials and service configuration to config.yaml.
Change to the python subfolder before running the sample scripts.
The demo uses requests, pyyaml, and tqdm. Credentials are stored in config.yaml, and authentication tokens are managed automatically.
Do not commit config.yaml or generated .token files to source control.
Run the complete workflow
Run:
python knowledgebase.py
To use a specific PDF:
python knowledgebase.py --document=<path-to-pdf>
The demo:
- Authenticates with the API.
- Creates a collection named demo-collection.
- Uploads a PDF.
- Monitors the document until indexing completes.
- Runs an inference request against the processed document.
Upload and indexing are distinct parts of document ingestion. Indexing extracts the document content and makes it available to AI operations.
If you don't specify a PDF, the demo selects one from the package's documents directory. Document processing times out after five minutes if it doesn't reach a complete state.
Note
The complete workflow creates a collection named demo-collection and uploads a PDF to it. The demo does not delete the collection or uploaded document when the workflow finishes.
Explore collection operations
After running the complete workflow, use individual scripts to explore specific API operations.
Create a collection
python collection.py --action create --name <collection-name>
Collection names can contain up to 255 characters.
List collections
python collection.py --action list
Choose whether to list collections created by you, shared by you, or shared by others when prompted.
Share a collection
python collection.py --action share --collection-id <collection-id>
Enter the email addresses that should receive read or write access when prompted.
Upload documents
python collection.py --action upload --collection-id <collection-id> --path=<path-to-file-or-directory>
The script can upload a single file or documents from a specified directory.
List documents in a collection
python collection.py --action get_documents --collection-id <collection-id>
Check document processing status
python collection.py --action get_status --document-id <document-id>
The demo provides these operations as standalone examples that you can inspect and adapt independently of the complete workflow.
Explore inference operations
The inference examples require a collection ID and document ID. Use the collection scripts to identify them:
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
Question answering
List your collections and documents, then run the Q&A example:
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --questionAnswer
Enter the collection ID, document ID, and question when prompted.
Document summarization
Identify the collection and document, then run the summarization example:
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --summarize
Enter the collection ID and document ID when prompted.
Context search
Identify the collection and document, then run the context-search example:
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --context-search
Enter the collection ID, document ID, and search text when prompted.
Property extraction
Identify the collection and document, then run the extraction example:
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --extract
Enter the collection ID, document ID, property name, extraction prompt, data type, and optional description when prompted.
Continue building with the API
The Python Demo provides working implementation patterns rather than complete API documentation.
Use Get started with the Knowledge Base API to understand the API resource model, document lifecycle, inference behavior, and response handling.
Use the Knowledge Base API reference when you need current endpoint paths, parameters, request and response schemas, and status information.
Troubleshooting
The demo writes detailed diagnostic information to:
logs/knowledgebase-demo.log
The log file records DEBUG-level information, while the console displays WARNING-level messages and above.
If an operation fails:
- Review logs/kinowledgebase-demo.log for request and authentication details.
- Verify the settings in config.yaml.
- Confirm that the PDF you're using exists and is accessible.
- Confirm that the application is using the appropriate service endpoint for your organization.
- Confirm that the authenticated identity has access to the requested resource.
- For API failures, retain the X-Request-ID returned in the response headers when available. Support can use this identifier to trace the request.
Implementation considerations
- The complete workflow accepts PDF files.
- The demo manages authentication tokens after API access is configured.
- API operations use the permissions available to the authenticated identity.
- The source package includes regional endpoint-discovery functionality, but production endpoint values should come from the current Knowledge Base API documentation rather than legacy values included with the demo.
