Python API

Resolve. Clarify. Resume.

A small directory example shows how a conversation becomes an explicit decision.

API preview

Source access is currently limited. Public installation instructions will accompany the first public release. The examples below describe the v0.10 API.

Resolve a name

The directory contains Alex Chen and Alex Rivera. Both share the alias “Alex.” This example needs no model key once the library is installed.

Python

import asyncio
from superer import AdaptiveResolver, ResolutionSession
from superer.domain_packs import directory_pack

async def main():
    pack = directory_pack("notify")
    resolver = AdaptiveResolver(pack.catalog)
    session = ResolutionSession(
        resolver, pack.contract, pack.parser
    )
    try:
        view, _ = await session.submit(
            "Notify Alex", expected_revision=0
        )
        for question in view.questions:
            print(f"Choose a match for {question.phrase}:")
            for option in question.options:
                print(option.index, option.label)
    finally:
        resolver.close()

asyncio.run(main())

Output

Choose a match for Alex:
1 Alex Chen
2 Alex Rivera
0 None of these — provide a corrected reference

Accept a user selection

Render the returned options in your application. Pass back the index selected by the user, together with the revision of the view they saw.

Python

question = view.questions[0]
# user_choice is the index selected in your UI.
view = await session.answer(
    question, user_choice,
    expected_revision=view.revision,
)
if view.decision and view.decision.action:
    parameters = dict(view.decision.action.parameters)

These statements belong inside the session’s try block, before closing the resolver. Selecting Alex Chen produces:

JSON

{
  "person_id": "person:1",
  "email": "alex.chen@example.org"
}

Keep execution separate

A proposed action is validated data, not a sent notification. Your application checks authorization and current evidence, then executes the tool with its own idempotency and failure handling.

Change what the tool needs

Using directory_pack("route") changes the contract to a team destination. Both Alex candidates belong to Support, so “Route the ticket to Alex” produces {"team": "support"} without claiming to know which person was intended.

Connect a real catalog