Quick start: using aat in Python

First configure a dspy.LM with the same information you would use to configure command-line programs or Marimo notebooks:

import dspy
dspy.configure(lm=dspy.LM(model="litellm_proxy/anthropic/Claude Opus 5",
                           api_base="https://api_url/litellm",
                           api_key="your-key-here"))

You can analyze a single string with the analyze_passage function. (If you include a --context citation with a value like a CTS URN, all results will be keyed to unique token IDs within the unique citation context.)

from aat.english import analyze_passage
tokens, graph = analyze_passage("Four score and seven years ago our fathers brought forth, upon this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal.")

analyze_passage returns two values. tokens is a complete tokenization of the input. (In this example, the list has 35 tokens.)

graph is an AATGraph. This snippet illustrates the actions function, which returns a list of all the AATNodes in the graph with type action. The agents_for and targets_for functions return a (possibly empty) list of AATNodes related to a given action, with type agent and target respectively.

for action in graph.actions():
    agents = graph.agents_for(action)
    targets = graph.targets_for(action)
    print(f"{action.value!r} (independent={action.related_node is None})")
    for a in agents:
        print(f"  agent:  {a.value!r}")
    for t in targets:
        print(f"  target: {t.value!r}")

Here is the output printed by the snippet above:

'brought' (independent=True)
  agent:  'fathers'
  target: 'nation'
'conceived' (independent=False)
  target: 'nation'
'dedicated' (independent=False)
  target: 'nation'
'are created' (independent=False)
  target: 'men'

Analyzing multiple citable passages

You can also analyzed texts structured in CitedPassage objects organizing citation and text content with the analyze_passages (plural) function. It returns the same pair of (tokens, graph) as analyze_passage:

from aat.core import CitedPassage
from aat.english import analyze_passages

passages = [
    CitedPassage(context="urn:cts:aat:examples.gettysburg.hay:1", text="Four score and seven years ago our fathers brought forth, upon this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal."),
    CitedPassage(context="urn:cts:aat:examples.gettysburg.hay:2", text="Now we are engaged in a great civil war, testing whether that nation, or any nation so conceived, and so dedicated, can long endure."),
]
tokens, graph = analyze_passages(passages)