# BooleanConcept [`BooleanConcept`](https://contextgem.shcherbak.ai/api/concepts/index.html.md#contextgem.public.concepts.BooleanConcept) is a specialized concept type that evaluates document content and produces True/False assessments based on specific criteria, conditions, or properties you define. ## 📝 Overview [`BooleanConcept`](https://contextgem.shcherbak.ai/api/concepts/index.html.md#contextgem.public.concepts.BooleanConcept) is used when you need to determine if a document contains or satisfies specific attributes, properties, or conditions that can be represented as True or False values, such as: * **Presence checks**: contains confidential information, includes specific clauses, mentions certain topics * **Compliance assessments**: meets regulatory requirements, follows specific formatting standards * **Binary classifications**: is favorable/unfavorable, is complete/incomplete, is approved/rejected ## 💻 Usage Example Here’s a simple example of how to use [`BooleanConcept`](https://contextgem.shcherbak.ai/api/concepts/index.html.md#contextgem.public.concepts.BooleanConcept) to determine if a document mentions confidential information: ```python # ContextGem: BooleanConcept Extraction import os from contextgem import BooleanConcept, Document, DocumentLLM # Create a Document object from text doc = Document( raw_text="This document contains confidential information and should not be shared publicly." ) # Define a BooleanConcept to detect confidential content confidentiality_concept = BooleanConcept( name="Is confidential", description="Whether the document contains confidential information", ) # Attach the concept to the document doc.add_concepts([confidentiality_concept]) # Configure DocumentLLM with your API parameters llm = DocumentLLM( model="openai/gpt-6-luna", api_key=os.getenv("CONTEXTGEM_OPENAI_API_KEY"), ) # Extract the concept from the document confidentiality_concept = llm.extract_concepts_from_document(doc)[0] # Print the extracted value print(confidentiality_concept.extracted_items[0].value) # Output: True # Or access the extracted value from the document object print(doc.concepts[0].extracted_items[0].value) # Output: True ``` ## ⚙️ Parameters When creating a [`BooleanConcept`](https://contextgem.shcherbak.ai/api/concepts/index.html.md#contextgem.public.concepts.BooleanConcept), you can specify the following parameters: | Parameter | Type | Default Value | Description | |---------------------------|----------------|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `name` | `str` | (Required) | A unique name identifier for the concept | | `description` | `str` | (Required) | A clear description of what condition or property the concept evaluates and the criteria for determining true or false values | | `model_role` | `str | None` | `None` | The role label of the model that extracts the concept when a model group is used: the concept is routed to the model in the group with the same `role`. With the default `None`, the concept is routed to the model without a role. Ignored when a single model is used, as it extracts every concept it is given. For more details, see [🏷️ Model Roles](https://contextgem.shcherbak.ai/optimizations/optimization_choosing_llm/index.html.md#model-roles-label). | | `modality` | `str` | `"text"` | The document content the concept is extracted from. Available values: `"text"`, `"image"`, `"multimodal"` (text and/or images, whichever the document has). `"image"` and `"multimodal"` are supported for document-level concepts only, and require an LLM that supports vision when the document has images. A concept with `"image"` cannot have `add_references=True`. A decision model extracts from text only, and rejects `"image"` and `"multimodal"` with `ValueError` before any request is sent (see [✅ Supported Aspects and Concepts](https://contextgem.shcherbak.ai/decision_models/decision_models/index.html.md#decision-models-supported-label)). For more details, see [🖼️ Concept Modality](https://contextgem.shcherbak.ai/optimizations/optimization_choosing_llm/index.html.md#concept-modality-label). | | `add_justifications` | `bool` | `False` | Whether to include justifications for extracted items. Justifications provide explanations of why the LLM extracted specific values and the reasoning behind the extraction, which is especially useful for complex extractions or when debugging results. A decision model provides no justifications, and rejects `True` with `ValueError` before any request is sent (see [✅ Supported Aspects and Concepts](https://contextgem.shcherbak.ai/decision_models/decision_models/index.html.md#decision-models-supported-label)). | | `justification_depth` | `str` | `"brief"` | Justification detail level. Available values: `"brief"`, `"balanced"`, `"comprehensive"`. | | `justification_max_sents` | `int` | `2` | Maximum sentences in a justification. | | `add_references` | `bool` | `False` | Whether to include source references for extracted items. References indicate the specific locations in the document where evidence supporting the boolean determination was found, helping to trace back the true/false value to relevant content that influenced the decision. A decision model provides no references for concepts, and rejects `True` with `ValueError` before any request is sent (see [✅ Supported Aspects and Concepts](https://contextgem.shcherbak.ai/decision_models/decision_models/index.html.md#decision-models-supported-label)). | | `reference_depth` | `str` | `"paragraphs"` | Source reference granularity. Available values: `"paragraphs"`, `"sentences"`. | | `decision_threshold` | `float | None` | `None` | Relevant when the concept is extracted by a decision model ([`DocumentDecisionModel`](https://contextgem.shcherbak.ai/api/decision_models/index.html.md#contextgem.public.decision_models.DocumentDecisionModel)): the lowest probability of “yes” (above 0, up to 1) with which the value of the concept is set to `True`. With the default `None`, the `decision_threshold` of the decision model applies. Ignored when the concept is extracted by an LLM. See [🎚️ Decision Threshold](https://contextgem.shcherbak.ai/decision_models/decision_models/index.html.md#decision-models-threshold-label). | | `singular_occurrence` | `bool` | `False` | Whether this concept has at most one extracted item. If `True`, at most one item is extracted, and none if there is nothing to extract: an LLM that returns more than one is asked again, as for any other invalid data. For boolean concepts, this parameter is particularly useful when you want to make a single true/false determination about the entire document (e.g., “contains confidential information”) or a unique determination about a specific matter (e.g., “is the payment schedule finalized”). This helps distinguish between evaluating overall document properties versus identifying multiple instances where a condition might be true/false. Note that with advanced LLMs, this constraint may not be required as they can often infer the appropriate number of items to extract from the concept’s name, description, and type (e.g., “contains confidential information” vs “compliance violations”). With a decision model ([`DocumentDecisionModel`](https://contextgem.shcherbak.ai/api/decision_models/index.html.md#contextgem.public.decision_models.DocumentDecisionModel)), a concept gets at most one item with or without this parameter, unless the text is sent in parts, i.e. `max_paragraphs_to_analyze_per_call` is passed to the extraction method: a decision model then returns an item for each part, and rejects a concept with `singular_occurrence=True` with `ValueError` before any request is sent. See [sending a long text in parts](https://contextgem.shcherbak.ai/decision_models/decision_models/index.html.md#decision-models-parts-label). | | `custom_data` | `dict` | `{}` | Optional. Dictionary for storing any additional data that you want to associate with the concept. This data must be JSON-serializable. This data is not used for extraction but can be useful for custom processing or downstream tasks. | ## 🚀 Advanced Usage ### 🔍 References and Justifications for Extraction You can configure a [`BooleanConcept`](https://contextgem.shcherbak.ai/api/concepts/index.html.md#contextgem.public.concepts.BooleanConcept) to include justifications and references. Justifications help explain the reasoning behind true/false determinations, while references point to the specific parts of the document that influenced the decision: ```python # ContextGem: BooleanConcept Extraction with References and Justifications import os from contextgem import BooleanConcept, Document, DocumentLLM # Sample document text containing policy information policy_text = """ Company Data Retention Policy (Updated 2024) All customer data must be encrypted at rest and in transit using industry-standard encryption protocols. Personal information should be retained for no longer than 3 years after the customer relationship ends. Employees are required to complete data privacy training annually. """ # Create a Document from the text doc = Document(raw_text=policy_text) # Create a BooleanConcept with justifications and references enabled compliance_concept = BooleanConcept( name="Has encryption requirement", description="Whether the document specifies that data must be encrypted", add_justifications=True, # Enable justifications to understand reasoning justification_depth="brief", justification_max_sents=1, # Allow up to 1 sentence for each justification add_references=True, # Include references to source text reference_depth="sentences", # Reference specific sentences rather than paragraphs ) # Attach the concept to the document doc.add_concepts([compliance_concept]) # Configure DocumentLLM with your API parameters llm = DocumentLLM( model="openai/gpt-6-luna", api_key=os.getenv("CONTEXTGEM_OPENAI_API_KEY"), ) # Extract the concept compliance_concept = llm.extract_concepts_from_document(doc)[0] # Print the extracted value with justification and references print(f"Has encryption requirement: {compliance_concept.extracted_items[0].value}") print(f"\nJustification: {compliance_concept.extracted_items[0].justification}") print("\nSource references:") for sent in compliance_concept.extracted_items[0].reference_sentences: print(f"- {sent.raw_text}") ``` ## 📊 Extracted Items When a [`BooleanConcept`](https://contextgem.shcherbak.ai/api/concepts/index.html.md#contextgem.public.concepts.BooleanConcept) is extracted, it is populated with **a list of extracted items** accessible through the `.extracted_items` property. Each item is an instance of the `_BooleanItem` class with the following attributes: | Attribute | Type | Description | |------------------------|---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `value` | bool | The extracted boolean value (True or False) | | `justification` | str | Explanation of why this boolean value was determined (only if `add_justifications=True`) | | `probabilities` | dict[bool, float] | Probabilities of `True` and `False`, e.g. `{True: 0.83, False: 0.17}` (only if the concept is extracted by a decision model, `None` otherwise; see [🎲 Probabilities of Extracted Items](https://contextgem.shcherbak.ai/decision_models/decision_models/index.html.md#decision-models-probabilities-label)) | | `reference_paragraphs` | list[[`Paragraph`](https://contextgem.shcherbak.ai/api/paragraphs/index.html.md#contextgem.public.paragraphs.Paragraph)] | List of paragraph objects that influenced the boolean determination (only if `add_references=True`) | | `reference_sentences` | list[[`Sentence`](https://contextgem.shcherbak.ai/api/sentences/index.html.md#contextgem.public.sentences.Sentence)] | List of sentence objects that influenced the boolean determination (only if `add_references=True` and `reference_depth="sentences"`) | #### NOTE To find the position of a reference paragraph or sentence in the document, e.g. to cite it or to retrieve its surrounding context, see [📍 Locating Paragraphs and Sentences](https://contextgem.shcherbak.ai/documents/document_config/index.html.md#locating-paras-and-sents). ## 💡 Best Practices Here are some best practices to optimize your use of [`BooleanConcept`](https://contextgem.shcherbak.ai/api/concepts/index.html.md#contextgem.public.concepts.BooleanConcept): - Provide a clear and specific description that helps the LLM understand exactly what condition to evaluate, using precise and unambiguous language in your concept names and descriptions. Since boolean concepts yield true/false values, focus on describing what criteria should be used to make the determination (e.g., *“whether the document mentions specific compliance requirements”* rather than just *“compliance requirements”*). Avoid vague terms that could be interpreted multiple ways—for example, use *“contains legally binding obligations”* instead of *“contains important content”* to ensure consistent and accurate determinations. - Break down complex conditions into multiple simpler boolean concepts when appropriate. Instead of one concept checking *“document is complete and compliant and approved,”* consider separate concepts for each condition. This provides more granular insights and makes it easier to identify specific issues when any condition fails. - Enable justifications (using `add_justifications=True`) when you need to understand the reasoning behind the LLM’s true/false determination. - Enable references (using `add_references=True`) when you need to trace back to specific parts of the document that influenced the boolean decision or verify the evidence used to make the determination. - Use `singular_occurrence=True` to enforce only a single boolean determination for the entire document. This is particularly useful for concepts that should yield a single true/false answer, such as *“contains confidential information”* or *“is compliant with regulations,”* rather than identifying multiple instances where the condition might be true or false throughout the document.