NPM Package

[Luceium]

Hey @steeevin88, @joshua-demo, @jonathanguven, and myself are working on creating an NPM package for uAgents. This discussion will serve as a place to talk about our progress, and for our team to solicit feedback from the Fetch AI Agents Team.

[ejfitzgerald]

Nice one guys! Excited to see what you guys put together 😁

When you think that you are close to an MVP please let us know - we would be keen to help out 👍

[Luceium]

Quick update on a hurdle. When creating digests, we need to ensure that they match Python digests for cross-platform and backward compatibility. I created #570 to document an issue that puts more responsibility on the user to create a model that is compatible with Python agents. This has become a recurring theme. Pydantic handles open API schema generation for Python and introduces a few quirks that need to be ported to the NPM package. For example, Pydantic automatically separates key-value pairs and elements in arrays with a space. Pydantic also automatically adds titles to all attributes where the title appears to be the attribute name separated into words and capitalized. As much as possible I tried to cover up these quirks but, the user still needs to write their model in a way that allows us to copy the Pydantic open api generation.

Here's a a python model that evaluates too: model:21e34819ee8106722968c39fdafc104bab0866f1c73c71fd4d2475be285605e9

class SuperImportantCheck(Model):
    """Plus random docstring"""
    check: bool
    message: str
    counter: int

The equivalent npm model in our current implementation looks like this

const schema = z
  .object({
    check: z.boolean(),
    message: z.string(),
    counter: z.number().int(),
  })
  .openapi({
    description: "Plus random docstring",
    title: "SuperImportantCheck",
  });

[jrriehl]

Thanks for the updates, it sounds like you guys are making great progress! I'd encourage you not to feel too constrained by the current schemas and digests produced by Pydantic, as we will definitely need a major revision of this in the near future which will break compatibility with previous versions. For example, if we need to omit certain fields or their are discrepancies in the whitespace or casing and it's easier to resolve on the Python side, that can be an option. Ultimately, we will need to specify the schemas and digests independently of Pydantic to guarantee cross-platform compatibility.

We've already had several internal discussions around this topic, but if you encounter blockers like this or have some specific recommendations, please continue to share them, because we will hopefully be able to resolve them together.

[Luceium]

Thanks for the update. I've started looking into what alternative libraries could be used for both. Unfortunately, it seems there are few options. However, I think I've developed a few ideas to improve compatibility.
The following ideas come from two observations:

• Open API schema's value is derived from the representation of useful information to interact with an endpoint
• digests's value is derived from the ability to identify unique objects.

Build digests on subsets of the open API schema that identify the model

A digest should identify a unique model. For cross-compatibility, uAgents libs must produce the same digest for the same model.
If models contain the same data, types, and constraints they are identical models and compatible inputs for the endpoint. Descriptors like names and descriptions provide value to the open API schema however, they don't change the model and should not result in different digests.

I'm suggesting that we produce open API schemas as normal but, the digest should be built on a subset that only includes attributes, values, types, and other constraints. To ensure compatibility, the subset needs to be sorted recursively.

Example of current implementation challenges

Pydantic's openapi schema production includes name fields for each attribute of a model.
See the following python model and openapi json outputs:

class SuperImportantCheck(Model):
    """Plus random docstring"""
    check: bool
    message: str
    counter: int

{"description": "Plus random docstring", "properties": {"check": {"title": "Check", "type": "boolean"},
 "counter": {"title": "Counter", "type": "integer"}, "message": {"title": "Message", "type": "string"}},
"required": ["check", "message", "counter"], "title": "SuperImportantCheck", "type": "object"}

In the NPM package I am currently adding default names to attributes to minimize the friction the user experiences.
For example, the name of the class / zod schema isn't meanigful to the identity of the open api schema but, because Pydantic uses it, the user needs to remember to add .openapi({title:"SuperImportantCheck"}) to achieve the same digest.

Changes necessary

Python

We could continue to use Pydantic to produce the open api schema however, when producing the digest we would introduce a step to process the schema, sort, and filter it. This can be accomplished by adding a config

NPM

We can continue to use zod + zod-openapi. Similar to the change needed for Python, we would need to sort and filter the schema before producing a schema.

Example of current implementation challenges

Pydantic's openapi schema production includes name fields for each attribute of a model.
See the following python model and openapi json outputs:

class SuperImportantCheck(Model):
    """Plus random docstring"""
    check: bool
    message: str
    counter: int

{"description": "Plus random docstring", "properties": {"check": {"title": "Check", "type": "boolean"},
 "counter": {"title": "Counter", "type": "integer"}, "message": {"title": "Message", "type": "string"}},
"required": ["check", "message", "counter"], "title": "SuperImportantCheck", "type": "object"}

In the NPM package, I am currently adding default names to attributes to minimize the friction the user experiences.
For example, the name of the class / zod schema isn't meaningful to the identity of the open API schema but, because Pydantic uses it, the user needs to remember to add .openapi({title: "SuperImportantCheck"}) to achieve the same digest.

Discontinue referential schema usage

Another realization is that ref's are useful for components that will be reused. However, are we expecting component reuse? And more importantly is it worth making the schema's not match? Like above, I don't think a recursive and ref-based output should be considered different. We have two options, we can use ref's but process them such that the digest is based on a strictly no-ref output or we can disallow refs in our open api generation.

Example of current implementation challenges

In the NPM package a model can be defined in a few ways. Two main considerations are the use of nested or complete schemas.

const engineSchema = z.object({
  size: z.number().int()
})

const schema = z.object({
  engine: engineSchema
})

const schema = z.object({
  engine: z.object({
    size: z.number().int()
   })
}).openapi({title: "Engine"});

Both implementations accomplish the same goals but, only the first one can be converted to use refs with createSchema(component, {...schemaOptions, components: {comp1, comp2, ...}})

For reference here is the current Python equivalent model and the stringified output

class Engine(Model):
    size:int

class Car(Model):
    engine:Engine

{"definitions": {"Engine": {"properties": {"size": {"title": "Size", "type": "integer"}}, "required": ["size"], "title": "Engine", "type": "object"}}, "properties": {"engine": {"$ref": "#/definitions/Engine"}}, "required": ["engine"], "title": "Car", "type": "object"}

An example of the ideal developer experience

To best illustrate the ideal developer experience I've created models in Python and Typescript that have different orders, nesting vs ref, and different descriptive fields. I've also written the ideal example json format to be used for digest creation.

Python

class EngineType(Enum):
  HV = "hv"
  GV = "gv"
  EV = "ev"

class Engine(Model):
    """ Standard engine info """
    type:EngineType
    size:int = field(description="The size of the engine from 0-16", ge=0, le=16)

class Car(Model):
    engine:Engine

NPM

As mentioned above there should be many valid approaches

const schema = z.object({
  engine: z.object({
    size: z.number().int().gte(0).lte(16).openapi({title: EngineSize, description: "Standard FetchAI engine size"})
    type: z.enum(['ev','hv','gv'])
   })
})

Open API JSON Schema used for digest creation

{
    "properties": {
        "engine": {
            "properties": {
                "size": {
                    "maximum": 16,
                    "minimum": 0,
                    "type": "integer"
                },
                "type": {
                    "enum": ["ev", "gv", "hv"],
                    "type": "string"
                }
            },
            "required": ["size", "type"],
            "type": "object"
        }
    },
    "required": ["engine"],
    "type": "object"
}

The openapi schema is left in a readable state to best illustrate the desired schema.
Note the order of attributes, the lack of descriptive attributes, and the lack of refs.
Despite minor differences in the Python and NPM model's both should produce the same schema with no additional effort on the developers' behalf.

Going forward

For now, I'm going to make the zod-openapi schema use refs to match Python outputs.

Useful links

• https://docs.pydantic.dev/1.10/usage/schema/#schema-customization
  • Demonstrates how to use schema-extra to remove fields like title
• https://github.com/samchungy/zod-openapi?tab=readme-ov-file#createschemaoptions
  • Shows how to use refs with zod-openapi
• github.com/Is it possible to have a schema with no $ref references ? pydantic/pydantic#889
  • Issue described well at the top
  • A Pydantic solution is described near the end
  • A simple solution using jsonref is described at the end
• https://github.com/gazpachoking/jsonref/blob/f21e8af20f71e2bc9705d152657134d300b0ddb4/jsonref/__init__.py#L284
  • Shows details on the simple jsonref solution described above