# StringConcept [`StringConcept`](https://contextgem.shcherbak.ai/api/concepts/index.html.md#contextgem.public.concepts.StringConcept) is a versatile concept type in ContextGem that extracts text-based information from documents, ranging from simple data fields to complex analytical insights. ## 📝 Overview [`StringConcept`](https://contextgem.shcherbak.ai/api/concepts/index.html.md#contextgem.public.concepts.StringConcept) is used when you need to extract text values from documents, including: * **Simple fields**: names, titles, descriptions, identifiers * **Complex analyses**: conclusions, assessments, recommendations, summaries * **Detected elements**: anomalies, patterns, key findings, critical insights ## 💻 Usage Example Here’s a simple example of how to use [`StringConcept`](https://contextgem.shcherbak.ai/api/concepts/index.html.md#contextgem.public.concepts.StringConcept) to extract a person’s name from a document: ```python # ContextGem: StringConcept Extraction import os from contextgem import Document, DocumentLLM, StringConcept # Create a Document object from text doc = Document(raw_text="My name is John Smith and I am 30 years old.") # Define a StringConcept to extract a person's name name_concept = StringConcept( name="Person name", description="Full name of the person", ) # Attach the concept to the document doc.add_concepts([name_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 name_concept = llm.extract_concepts_from_document(doc)[0] # Get the extracted value print(name_concept.extracted_items[0].value) # Output: "John Smith" # Or access the extracted value from the document object print(doc.concepts[0].extracted_items[0].value) # Output: "John Smith" ``` ## ⚙️ Parameters When creating a [`StringConcept`](https://contextgem.shcherbak.ai/api/concepts/index.html.md#contextgem.public.concepts.StringConcept), 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 the concept represents and what should be extracted | | `examples` | `list[StringExample]` | `[]` | Optional. Example values that help the LLM better understand what to extract and the expected format (e.g., *“Party Name (Role)”* format for contract parties). This additional guidance helps improve extraction accuracy and consistency. | | `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`. 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. | | `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 the information was either directly found or from which it was inferred, helping to trace back extracted values to their source content even when the extraction involves reasoning or interpretation. | | `reference_depth` | `str` | `"paragraphs"` | Source reference granularity. Available values: `"paragraphs"`, `"sentences"`. | | `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. This is particularly relevant when it might be unclear for the LLM whether to focus on the concept as a single item or extract multiple items. For example, when extracting the total amount of payments in a contract, where payments might be mentioned in different parts of the document but you only want the final total. Note that with advanced LLMs, this constraint may not be strictly required as they can often infer the appropriate number of items to extract from the concept’s name, description, and type (e.g., “document title” vs “key findings”). | | `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 ### ✏️ Adding Examples You can add examples to improve the extraction accuracy and set the expected format for a [`StringConcept`](https://contextgem.shcherbak.ai/api/concepts/index.html.md#contextgem.public.concepts.StringConcept): ```python # ContextGem: StringConcept Extraction with Examples import os from contextgem import Document, DocumentLLM, StringConcept, StringExample # Create a Document object from text contract_text = """ SERVICE AGREEMENT This Service Agreement (the "Agreement") is entered into as of January 15, 2025 by and between: XYZ Innovations Inc., a Delaware corporation with offices at 123 Tech Avenue, San Francisco, CA ("Provider"), and Omega Enterprises LLC, a New York limited liability company with offices at 456 Business Plaza, New York, NY ("Customer"). """ doc = Document(raw_text=contract_text) # Create a StringConcept for extracting parties and their roles parties_concept = StringConcept( name="Contract parties", description="Names of parties and their roles in the contract", examples=[ StringExample(content="Acme Corporation (Supplier)"), StringExample(content="TechGroup Inc. (Client)"), ], # add examples providing additional guidance to the LLM ) # Attach the concept to the document doc.add_concepts([parties_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 parties_concept = llm.extract_concepts_from_document(doc)[0] # Print the extracted parties and their roles print("Extracted parties and roles:") for item in parties_concept.extracted_items: print(f"- {item.value}") # Expected output: # - XYZ Innovations Inc. (Provider) # - Omega Enterprises LLC (Customer) ``` ### 🔍 References and Justifications for Extraction You can configure a [`StringConcept`](https://contextgem.shcherbak.ai/api/concepts/index.html.md#contextgem.public.concepts.StringConcept) to include justifications and references. Justifications help explain the reasoning behind extracted values, especially for complex or inferred information like conclusions or assessments, while references point to the specific parts of the document that informed the extraction: ```python # ContextGem: StringConcept Extraction with References and Justifications import os from contextgem import Document, DocumentLLM, StringConcept # Sample document text containing financial information financial_text = """ 2024 Financial Performance Summary Revenue increased to $120 million in fiscal year 2024, representing 15% growth compared to the previous year. This growth was primarily driven by the expansion of our enterprise client base and the successful launch of our premium service tier. The Board has recommended a dividend of $1.25 per share, which will be payable to shareholders of record as of March 15, 2025. """ # Create a Document from the text doc = Document(raw_text=financial_text) # Create a StringConcept with justifications and references enabled key_figures_concept = StringConcept( name="Financial key figures", description="Important financial metrics and figures mentioned in the report", add_justifications=True, # enable justifications to understand extraction reasoning justification_depth="balanced", justification_max_sents=3, # allow up to 3 sentences 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([key_figures_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 key_figures_concept = llm.extract_concepts_from_document(doc)[0] # Print the extracted items with justifications and references print("Extracted financial key figures:") for item in key_figures_concept.extracted_items: print(f"\nFigure: {item.value}") print(f"Justification: {item.justification}") print("Source references:") for sent in item.reference_sentences: print(f"- {sent.raw_text}") ``` ## 📊 Extracted Items When a [`StringConcept`](https://contextgem.shcherbak.ai/api/concepts/index.html.md#contextgem.public.concepts.StringConcept) is extracted, it is populated with **a list of extracted items** accessible through the `.extracted_items` property. Each item is an instance of the `_StringItem` class with the following attributes: | Attribute | Type | Description | |------------------------|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------| | `value` | str | The extracted text string | | `justification` | str | Explanation of why this string was extracted (only if `add_justifications=True`) | | `reference_paragraphs` | list[[`Paragraph`](https://contextgem.shcherbak.ai/api/paragraphs/index.html.md#contextgem.public.paragraphs.Paragraph)] | List of paragraph objects that informed the extraction (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 informed the extraction (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 [`StringConcept`](https://contextgem.shcherbak.ai/api/concepts/index.html.md#contextgem.public.concepts.StringConcept): - Provide a clear and specific description that helps the LLM understand exactly what to extract. - Include examples (using [`StringExample`](https://contextgem.shcherbak.ai/api/examples/index.html.md#contextgem.public.examples.StringExample)) to improve extraction accuracy and demonstrate the expected format (e.g., *“Party Name (Role)”* for contract parties or *“Revenue: $X million”* for financial figures). - Enable justifications (using `add_justifications=True`) when you need to see why the LLM extracted certain values. - Enable references (using `add_references=True`) when you need to trace back to where in the document the information was found or understand what evidence informed extracted values (especially for inferred information). - When relevant, enforce only a single item extraction (using `singular_occurrence=True`).