Advanced usage of StringExample and other Example classes.

[chingologram]

Hi, first of all, thanks for this package. It is coming very useful for a task where I'm needing to extract bibliographical references from a set of academic papers.
I am using the StringExample class to extract author names from the bibliography sections of papers.
I would like to use the StringExample class to extract author concepts. I was wondering if it would be possible to achieve this:

• Provide negative examples. For example, instruct the model to ignore proper names when they are not part of an APA citation (for example, in a signature, or when a person is mentioned but not quoted).
• Provide the context where the example works. For example, I would like to provide a model for an APA citation. For example, if the context was Balderston, D. (2001). Borges and the art of narrative. In H. Bloom (Ed.), Jorge Luis Borges (pp. 45–68). Chelsea House., then the content value of the example should be only the author, let's say "Balderston, D.", but not the editor (H. Bloom) or the person appearing in the title (Jorge Luis Borges)

Is any of this possible? Can you think of another approach to achieve this? Thanks in advance!

[SergiiShcherbak]

Thanks for the kind words- great use case.

Short answer:

• Negative examples are not supported in StringExample. You should use concept description to state exclusions explicitly, and scope extraction to the right context.
• You could try extracting authors only within a References/Bibliography aspect, then run your author concept on that aspect.
• If you need stricter control: use a structured concept (or classifier) and filter.

How you could do it:

• Scope to APA references (aspect), then extract authors (concept):

from contextgem import Aspect, Document, DocumentLLM, StringConcept, StringExample


doc = Document(raw_text="<paper_text>")

refs = Aspect(
    name="References",
    description="APA-style bibliography entries. Ignore signatures, acknowledgements, inline mentions.",
)
authors = StringConcept(
    name="APA authors",
    description=(
        "Return only author names from APA citations. "
        "Ignore editors and names appearing only in titles."
    ),
    examples=[
        StringExample(content="Balderston, D."),
        StringExample(content="Smith, J. A."),
    ],
)
refs.add_concepts([authors])
doc.add_aspects([refs])

llm = DocumentLLM(model="...", api_key="...")

doc= llm.extract_all(document=doc)

print([i.value for i in doc.aspects[0].concepts[0].extracted_items])

• For even tighter filtering, you could use JsonObjectConcept with structure like {"name": str, "role": Literal["author","editor","mentioned"]} and keep only role=="author".

This setup achieves “ignore non-APA mentions” via aspect scoping and “only the author, not editor/title names” via the concept description and examples.

Hope this helps!