DEV Community: InterSystems

Working with Dynamic Objects in IRIS: doubts that only come up when you need to deploy by tomorrow morning and it's 11 P.M.

InterSystems Developer — Sun, 30 Aug 2026 07:37:14 +0000

If you have spent any time on the Developer Community, you have seen the many questions return in different costumes: How do I turn a persistent object into JSON? How do I loop over a JSON payload whose shape I don't know? Why does Required do nothing on my %DynamicArray property? Why is my date coming back as 31390?

Noticing that, we decided to write an article summarizing all the questions that come with something that the documentation alone couldn't provide: practice.

Let's start with the foundation

InterSystems IRIS gives you two classes for schema-less data: %DynamicObject and %DynamicArray. Both inherit from %DynamicAbstractObject, and instances of either are called dynamic entities. They map cleanly onto JSON: an object is a set of key/value pairs, an array is an ordered list. Unlike a persistent or registered class, a dynamic object keeps no predefined list of valid property names — every string key is legal, and you add or remove members at runtime.

The most pleasant part is the literal syntax, which will look familiar to anyone coming from JavaScript:

Set person = {"name":"Ada","active":true,"roles":["admin","dev"]}
Set scores = [90, 85, 77]

You can also build them field by field. %Set() returns the entity it modified, so calls chain:

Set obj = {}.%Set("a",1).%Set("b",2) // now obj is {"a":1,"b":2}

Do scores.%Push(100)                 // now scores is [90, 85, 77, 100]

Set last = scores.%Pop()             // now scores is [90, 85, 77] and last is 100

%Push() and %Pop() exist only on arrays, but everything else works on both. To turn text into an entity, use %FromJSON() and to serialize back, use %ToJSON():

Set jsonString = "{""field"": ""value""}"
Set obj = {}.%FromJSON(jsonString) // now obj is {"field": "value"}

Write obj.%ToJSON()                // this outputs "{""field"": ""value""}"

%FromJSON() also accepts a stream, and %FromJSONFile() reads straight from a filename (note: a filename string, rather than a %File object — a common trip-up).

Iterating over structure you don't control

When a payload arrives from another system, you often don't know how many elements it has or what they're called. Don't reach for a for loop by index. Dynamic arrays can be sparse, which means that an element can exist positionally without ever having been assigned, and a for loop will happily hand you those empty slots. The correct tool is %GetIterator(), which returns a %Iterator.Object or %Iterator.Array, driven by %GetNext():

Set iter = obj.%GetIterator()

While iter.%GetNext(.key, .value, .type) 
{
    Write !, key, " = ", value, " (", type, ")"
}

%GetNext() skips unassigned elements automatically, which is exactly why it is preferred. For an object, key is the property name. For an array, key is the index. To walk a nested structure, recurse whenever $IsObject(value) is true, as that will return true for both sub-objects and sub-arrays.

That third argument, .type, is easy to ignore, but worth understanding. When present it does two useful things. First, it returns the element's original JSON datatype as a string. Second — and this is the practical part — it changes the conversion rules so you avoid <MAXSTRING> errors: a very long JSON string is handed back as a read-only stream object instead of being force-fit into an ObjectScript string, and JSON numbers are returned in their original textual form rather than being coerced. If you're processing arbitrary external JSON, passing .type is cheap insurance.

Type discovery inside a dynamic entity

Because dynamic entities are untyped containers, IRIS gives you tools to interrogate them. %GetTypeOf(key) reports what a value actually is: number, string, boolean, object, array, null, oref, or unassigned:

Set a = [1, "test", true, {"v":1}, [1,2,3]]

// the indexes are:

//       0,      1,    2,       3,       4

Write a.%GetTypeOf(2)   // true: boolean


Write a.%GetTypeOf(3)   // {"v":1}: object


Write a.%GetTypeOf(9)   // unassigned - it finishes at index 4

This matters because ObjectScript flattens JSON's richer type system on the way in. JSON true, false, and null all become ObjectScript-friendly values 1, 0, and "" when you read them with dot syntax or %Get(). If you need to tell a genuine null apart from an empty string apart from a key that was never set, %GetTypeOf() is the reliable discriminator. There is also %IsDefined(), but it returns false for unassigned members and true for both "" and null.

The date gotcha

Type flattening is behind one of the community's recurring puzzles. Export a persistent object whose DOB is 1926-12-11 and you may see "DOB":31390 in the result — that 31390 is the internal $HOROLOG day count, not a corrupted value. The same logic bites the other direction in dynamic SQL: if you pass a query a literal like '1926-12-11' and get zero rows, it's usually because the column expects $HOROLOG internal format. The fix is to convert on the way in with $ZDATEH("1926-12-11", 3). Whenever a date crosses the boundary between JSON, SQL, and stored objects, ask which representation each side expects.

Two things both called "array"

Here is a distinction that quietly causes bugs. %DynamicArray is a positional list, indexed from 0. But ObjectScript also has typed collection properties, and the array of collection is not a positional array at all — it's a dictionary (a keyed map). Compare:

Property Tags As array of %String;   // a dictionary: key -> value

Property Notes As list of %String;   // an ordered, positional list

You access an array of collection by key, not by position:

Do obj.Tags.SetAt("high", "priority")

Write obj.Tags.GetAt("priority")     // high

Set key = ""


For 


{ 


    Set value = obj.Tags.GetNext(.key)  Quit:key=""


    Write !, key, ": ", value 


}

When a class using %JSON.Adapter serializes an array of property, it comes out as a JSON object{"priority":"high"}, whereas a list of comes out as a JSON array ["high"]. So "typed array" can mean two very different shapes on the wire depending on which collection you chose. If you want positional JSON, use list of (or a %DynamicArray); if you genuinely want a keyed lookup, array of is your dictionary.

Bridging persistent objects and dynamic objects

A frequent need is converting a stored object into a free-form dynamic one — for instance, to trim fields before returning them from a REST method. If your class extends %JSON.Adapter, the clean, non-deprecated path is a two-step that fits on one line:

Set sc = person.%JSONExportToString(.json)


Set dynObj = {}.%FromJSON(json)

(For large objects, swap in %JSONExportToStream() so you never hit the string length limit.) Two alternatives are worth knowing. Embedded SQL's JSON_OBJECT() lets you cherry-pick and rename columns when you only want a subset:

&sql(SELECT JSON_OBJECT('name':Name,'dob':DOB) INTO :json WHERE ID = 1)


Set dynObj = {}.%FromJSON(json)

And going the other way, %JSONImport() populates a persistent object from a dynamic one.

Where dynamic freedom ends: validation

Finally, the caveat that surprises people building JSON request validators. The Required property keyword works for literals, collections, streams, and object-valued properties — but it is silently ignored for %DynamicArray and %DynamicObject properties. The reason is mechanical: the generated getter defaults these to [] and {}, so even assigning "" gets overwritten with a non-empty default, and %ValidateObject() never sees a missing value. If you need to enforce presence or shape on dynamic properties, don't rely on Required — implement a %OnValidateObject() callback and check them yourself:

Method %OnValidateObject() As %Status


{


    If ..fieldOptions.%Size() = 0 


    {


        Return $$ERROR($$GeneralError, "fieldOptions is required")


    }

Return $$OK


}

Choosing well

Dynamic entities are the right tool when structure is unknown, external, or genuinely fluid — parsing payloads, assembling responses, staging data. Typed persistent classes remain the right tool when you want the database, indexes, and validation to enforce a contract. Most real systems use both, meeting at the %JSON.Adapter boundary. Keep three habits and you'll avoid the classic pitfalls: iterate with %GetNext() rather than by index, reach for %GetTypeOf() whenever a value's type actually matters, and remember that array of is a dictionary, not a list.

Disclaimer: this article has been written by human hands, but reviewed with Claude AI for (1) enhancing my English (not my first language) and (2) reminding me of topics I hadn't covered in the initial versions. The search and studies for sources and practice were all made by a human (me :D), and the agent used to review is trained only on my own articles, so that it copies my tone without plagiarism, with respect to my fellow community members. The final revision was done completely without AI.

InterSystems for dummies – IRIS Vector Search (Part II)

InterSystems Developer — Sun, 30 Aug 2026 07:30:53 +0000

After an extensive math lesson, we are going to put our new knowledge into practice and create one of the best context-related databases.

Get your magnifying glasses and hats ready, because Vector Holmes is back.

Vector Calculation

To calculate the vector associated with a text, image, or sound, we will use a Python library called sentence-transformers, which allows us to transform content into a vector.
To implement this, we should create the following function:

ClassMethod Embedding(Text) [ Language = python ]
{
    from sentence_transformers import SentenceTransformer

    model_name = 'sentence-transformers/all-MiniLM-L6-v2'

    # Cache in global variables of the embedded Python module (persistent per process).
    global _cached_embedding_model
    if '_cached_embedding_model' not in globals():
        _cached_embedding_model = SentenceTransformer(model_name)

    vector = _cached_embedding_model.encode(
        [Text],
        normalize_embeddings=True,
        convert_to_numpy=True,
        show_progress_bar=False
    )

    return str(vector[0].tolist())
}

This method "vectorizes" the content of our text using a pre-trained library called "all-MiniLM-L6-v2". However, if you wish, you can modify it and utilize your own trained library.

First Steps

Note: To access the terminal of our Docker instance, use the following command:
Docker-compose exec iris iris session iris

Let's use an example of a vectorized search. For this, we will utilize a table called St.vectorsearch.Feeling that has the following fields:

Field	Type	Description
Text	%String	Text about how I feel
Value	%Integer	Identifier of my feeling (See attached table)
Vector	%Vector	Text vector value

You can create the data by running the following command:

Do ##class(St.vectorsearch.Data).Init()

Next, we are going to load the sentiment data from the /opt/irisbuild/data/training.csv directory, using the Populate command from the St.vectorsearch.Data class.

USER>do ##class(St.vectorsearch.Data).Populate()
Truncating table St_vectorsearch.Feeling
Preparing to load data from file training.csv
Loading data from file training.csv
Total records loaded: 2000
Calculating vectors for records...
Processing 496 of 2000

Be patient, since it will create a vector for each record, and it might take quite a while.

Note: Populate will initialize a data model of 2000 records. There is another file with 5410 records if you want more information in the data model. If you wish to work with that one, use the PopulateFull() command instead.

The values of feelings are as follows:

Feeling	Value
sadness	0
joy	1
love	2
anger	3
fear	4

For example:

“I left with my bouquet of red and yellow tulips under my arm, feeling slightly more optimistic than when I arrived.” It has a value of 1 (Joy).

“I can’t walk into a shop anywhere where I do not feel comfortable.” It has a value of 4 (Fear).

If we use this function to create vectors, the first text we pass will return the next vector:

.034666668623685836791, .012147962115705013276, .020678628236055374146, 
.043785430490970611572, .030321707949042320251, -.0081106657162308692932, 
-.028869708999991416931, -.059950094670057296752, .067945346236228942871, 
-.070874534547328948974, -.060159780085086822509, .016239311546087265014, 
-.034665744751691818237, -.011642633005976676941, .080176420509815216064, 
………
.0099751437082886695861, .0098187308758497238159, .00016082286310847848653, .013545278459787368774, -.0049553057178854942321, .054155148565769195556, .025806473568081855773, -.038503900170326232911, .039657127112150192261, 
-.073851920664310455322, -.070615962147712707519, .066068030893802642822, 
-.082378372550010681152, -.043505564332008361816, -.0054294602014124393463

Note: The vector value has been reduced to keep the text from being too long; the vector actually has 384 values.

If we look for another cheerful text when creating the vector, it will give us the following value.

Example:

“Today, I’m very happy.”

[-0.007015716750174761, 0.05171322077512741, 0.0045058708637952805, -0.04008815810084343, 0.009171668440103531, -0.04867621883749962, 0.08268272876739502, 0.004975424613803625, -0.062008269131183624, 
……
0.036987580358982086, 0.027985544875264168, 0.05382953956723213, 0.031146947294473648, -0.011256292462348938, 0.005441852379590273]

This data does not make sense right now because we are not going to make a value-by-value comparison. That means we are not going to look for a record with exactly the same value as the vector because each vector is different. For that, we will use the formulas explained in the first part.

We are going to use the following SQL commands to see which vectors are the closest to the vector we have calculated.

Dot Product Search

As we indicated in the first part, the dot product search tells us how aligned two different vectors are. That means the closer it is to 1, the closer, or rather more similar, two vectors are.

To perform our search, we will use the condition “VECTOR_DOT_PRODUCT” that compares two vectors to determine their alignment:

SELECT TOP 5 Text, Value
 FROM St_vectorsearch.Feeling
ORDER BY VECTOR_DOT_PRODUCT(Vector, TO_VECTOR('[-0.007015716750174761, 0.05171322077512741, 0.0045058708637952805, -0.04008815810084343, 0.009171668440103531, -0.04867621883749962, 
......
-0.036987580358982086, 0.027985544875264168, 0.05382953956723213, 0.031146947294473648, -0.011256292462348938, 0.005441852379590273]', float)) DESC

This search gives us the following results:

So… “Today, I’m very happy” returns most results with a value of 1, joy.

But… what is the percentage of proximity our text has regarding the rest of the retrieved values?

We can find that out by comparing it with the current vector and displaying the value in a percentage format.

SELECT TOP 5 Text, Value, TO_CHAR(VECTOR_DOT_PRODUCT(Vector, TO_VECTOR('[-0.007015716750174761, 0.05171322077512741, 0.0045058708637952805, -0.04008815810084343, 0.009171668440103531, -0.04867621883749962, 
......
 -0.036987580358982086, 0.027985544875264168, 0.05382953956723213, 0.031146947294473648, -0.011256292462348938, 0.005441852379590273]', float)) * 100 , '990.99%') AS Percentage
 FROM St_vectorsearch.Feeling
ORDER BY VECTOR_DOT_PRODUCT(Vector, TO_VECTOR('[-0.007015716750174761, 0.05171322077512741, 0.0045058708637952805, -0.04008815810084343, 0.009171668440103531, -0.04867621883749962, 
......
-0.036987580358982086, 0.027985544875264168, 0.05382953956723213, 0.031146947294473648, -0.011256292462348938, 0.005441852379590273]', float)) DESC

This search gives us the following results:

The percentage of similarity to the most matching text is 65%. Our mind knows that, among all the texts, the meaning of “Today, I’m very happy” is a feeling of joy, meaning it should be closer to 100% comparing to the text “I am feeling so happy”

Cosine Similarity Search

The cosine similarity search is performed using the cosine of the angle between the vectors being compared.

If we want to perform vector search with cosine similarity, we would have to utilize the condition “VECTOR_COSINE”, just as we have previously done it:

SELECT TOP 5 Text, Value, TO_CHAR(VECTOR_COSINE(Vector, TO_VECTOR('[-0.007015716750174761, 0.05171322077512741, 0.0045058708637952805, -0.04008815810084343, 0.009171668440103531, -0.04867621883749962, 
......
 -0.036987580358982086, 0.027985544875264168, 0.05382953956723213, 0.031146947294473648, -0.011256292462348938, 0.005441852379590273]', float)) * 100 , '990.99%') AS Percentage
 FROM St_vectorsearch.Feeling
ORDER BY VECTOR_COSINE(Vector, TO_VECTOR('[-0.007015716750174761, 0.05171322077512741, 0.0045058708637952805, -0.04008815810084343, 0.009171668440103531, -0.04867621883749962, 
......
-0.036987580358982086, 0.027985544875264168, 0.05382953956723213, 0.031146947294473648, -0.011256292462348938, 0.005441852379590273]', float)) DESC

Oh… surprise!! It gave us back the same results:

As mentioned in the first part, this type of search is more advisable for comparing more than one parameter, such as movie genre, lead actor, etc. In other words, this is how the movie recommendation system of Netflix or HBO works.

Does it Support Multiple Languages?

What will happen if, instead of using the text “Today, I’m very happy,” we do it in Spanish?

“Hoy, estoy muy feliz.”

The created vector (reducing the text for obvious reasons) will resemble the following:

[-0.020053215324878693, 0.08766797184944153, 0.04118209332227707, 0.027171766385436058, -0.026769554242491722, -0.045022152364254,
…..
 0.038541924208402634, 0.018977241590619087, 0.03448185324668884, 0.10012426972389221, 0.08426760882139206, -0.09713190793991089]

And if we use it to perform the search as we did previously, we will get the result below:

We got a combination of love (2), fear (4), and joy (1), when the meaning is identical to the English text.

This rather diverse result appeared because the word "feliz" is closer to "feel" than "happy".

As you have noticed, the creation of vectors is closer to the phonetics of the texts than to their meanings.

I recommend testing the same text in different languages.

Here you have the result of searching for it in French “Aujourd'hui, je suis très heureux”:

Therefore, if we want to use this system to search for text in a document that we have fully "tokenized", it can be solved in a very simple way.

In a nutshell, we are going to change the model we used to create the token to the model paraphrase-multilingual-MiniLM-L12-v2:

model_name = 'sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2'

Therefore, if we modify this line in the Embedding method, we can use multilingual support in data retrieval.

This is the result of using this model with the search in Spanish:

Now, if you create a language-based token, why does it internally "translate" "Feliz" to "Happy"? Yes, I have used double quotation marks around "translate" because it is not a context-based translation like in any other online dictionary. It interprets the word by creating a token, which can cause some confusion when similar words are used.

For example, in Spanish, the word "tiempo" is the same word for the meaning of the word "time" or "weather", so the token for this word could be confusing. Fortunately, the token is not based on a single word, but on a set of words that make up the phrase. It means that the rest of the phrase's context helps us create a token much closer to the final one. Therefore, our vector seems to have translated the text we want to search for.

Case Study

Very important note: I encountered some difficulties developing these practical examples. When trying to create a vector from an IRIS production environment, the process would completely freeze.

The solution to using the St.Vectorsearch.Vector.Embedding method without any issues was to download the model locally instead of querying the online model for each request. When using the model locally, invoking this class from production did not require an Internet connection to download the model, making the vector creation process much faster.

I have created a small demo to show how a text, entered from a form, is "tokenized" and searched in the database to find the five closest results.

http://localhost:52773/csp/user/feeling.html

Note: Make sure production is running. To do this, log in to the Management Portal and start production if it was stopped.

The first time you ask about a feeling, it may take a little while, because it caches the model for future queries.

This website invokes an API running on IRIS that converts the text into a vector. Then it invokes the SQL search as I mentioned previously.

It performs a search for the 5 closest phrases to the calculated vector. Then the website displays those results and indicates which sentiment is repeated more often, showing the arithmetic mean of the most repeated results.

Can We Have More Than One Element to Create a Vector?

In the sentiment example, the phrase included information we used to create a search vector. However, what do we need if we have more than one column to perform the search?

If we want someone to recommend a similar movie to the one we have already seen, the result will depend on many factors. It could be related to the movie release year (because you like older films) or the genre (comedy, drama, science fiction), etc.

In this case, we will create a vector based on the text that includes the fields we want to index. This way, we will have all the fields we wish to use for our query:

Note: The order of the data is important because if we are interested in films from the same year and genre, those columns will have the most weight in the index.

If we are looking for recommendations based on the plot, genre, director, and actors, that would be the order:

“Overview: [Overview]. Genre: [Genre]. Directed by [Director] and starring by [Star1], [Star2], [Star3] and [Star4]. Movie year [Year]. Ranking: [Rating]."

To understand the age classifications better, I will show you the meaning of those values:

Certificate	Description	Comment
A	A is Adults (equivalent to the USA R).	Rating in the UK
UA	UA is for ages 12 and up with parental supervision.	Rating in the UK
U	U is Universal (for everyone).	Rating in the UK
PG-13	PG-13 (Parents Strongly Cautioned): Strong warning for parents. Some materials may be inappropriate for children under the age of 13.	Current (MPA)
R	R (Restricted): Those under 17 years of age must be accompanied by a parent or adult guardian because it contains adult material.	Current (MPA)
PG	PG (Parental Guidance Suggested): Parental guidance is suggested. Some content may not be suitable for young children.	Current (MPA)
G	G (General Audiences): For all audiences.	Current (MPA)
PASSED	The film complies with the strict moral standards of the time to be shown in cinemas.	They were used between the 1930s and 1960s under the famous Hays Code.
TV-14	TV-14: Parents strongly advised. Contains material that many parents would consider inappropriate for children under the age of 14.	TV Parental Guidelines
16	Not recommended for children under 16 years old.	Typical numerical age classification of European or Latin American systems.
TV-MA	It may be inappropriate for viewers under the age of 17
due to graphic violence, explicit sexual activity, or crude language.	TV Parental Guidelines
UNRATED	Not classified.
GP	GP: It was a temporary code used in the early 1970s. It was equivalent to what we know today as PG (Parental Guidance Suggestion).
APPROVED	The film complies with the strict moral standards of the time in order to be shown in cinemas.	They were used between the 1930s and 1960s under the famous Hays Code.
TV-PG	Recommended parental guidance.	TV Parental Guidelines
U/A	U is Universal (for everyone).	Rating in the UK

In the same way that we initialized the table and loaded the data from the Feeling table, we employ the following commands:

Note: To access the terminal of our Docker instance, use the following command:
Docker-compose exec iris iris session iris

Do ##class(St.vectorsearch.Data).InitMovie()

Next, we will load the movie data from the /opt/irisbuild/data/imdb_top_1000.csv directory, using the PopulateMovie command from the St.vectorsearch.Data class.

USER>do ##class(St.Vectorsearch.Data).PopulateMovie()
Truncating table St_Vectorsearch.Movie
Preparing to load data from file imdb_top_1000.csv
Loading data from file imdb_top_1000.csv
Total records loaded: 999
Calculating vectors for records...
Processing 116 of 999

Note: During the demo initialization process in Docker, the test data loading operations are already performed.

In each movie, we have initialized the vector value using the phrase we have created with the different fields. I encourage everyone to make appropriate changes to the St.Vectorsearch.Data.PopulateMovie class to align with your priorities better.

As I mentioned in the first part, there is another vector approximation method (by cosine similarity), which allows us to search vectors that form the closest angle (those that are closest in the same direction).

That is why it is the best system to use if you wish to find data recommendations.

To use this, we will need the condition “VECTOR_COSINE”, which can tell us the closest angles to the indicated vector.

SELECT TOP 5 ID, Link, Title, Year
FROM St_Vectorsearch.Movie 
WHERE Title <> ? 
ORDER BY VECTOR_COSINE(Vector, TO_VECTOR(?, float)) DESC

In this case, we are going to look for movies that approximate the angle of the vector associated with the film we have, without, of course, having it recommend itself.

You can access the demo via the link below:

http://localhost:52773/csp/user/movies.html

In this case, the recommended films are similar to 1988's "Akira," although I would personally put "Kôkaku Kidôtai," also known as "Ghost in the Shell," first. They are similar because they are both animated films. Mental note: I still need to watch Papurika...

So, that is all for now. You have everything you need to work with vector indices, including practical examples and an application you can use for your experiments.

Please leave any suggestions or ideas you have in the comments, including practical ways to implement this knowledge, etc...

See you at the next “InterSystems for Dummies”!

InterSystems for dummies – IRIS Vector Search (Part I)

InterSystems Developer — Sun, 23 Aug 2026 15:35:13 +0000

You may have heard the term "Vector Search" before. Do not worry, though; it is not "Vector Holmes" investigating a crime from 221B Baker Street.

So, let’s explain, step by step, how to tackle vector data searches.

:::pagebreak:::

What Are Vectors?

In mathematics, a vector is an arrow that indicates a quantity with three elements: its value (magnitude), its direction, and its course. It is used to represent things that cannot be described with a single number, such as velocity, force, or displacement.

Magnitude: It is the length of the arrow, which indicates the numerical value of the magnitude.
Direction: It is the straight line on which the vector acts (it can be horizontal, vertical, or diagonal).
Course: Indicates where the arrow points (it is the endpoint of the direction).
Point of application: It is the starting point of the vector.

Two vectors are equal when they have the same magnitude (modulus), direction, and course. It means that regardless of their position in space, if their components are identical, they are the same vector.

Two vectors are opposite when they have the same magnitude and the same direction, but opposite course, meaning they are facing away from each other.

In a two-dimensional system, a vector is represented by its start (origin) and end (destination) coordinates on the X and Y axes.

These two vectors are represented as follows:

{(1,1),(5,3)}

{(2,4),(7,5)}

In a three-dimensional space, coordinates include the X, Y, and Z axes.

What Do Mathematical Vectors Have to Do with Vector Search?

Vector search is a method of searching known in numerical representations as vectors. It is similar to the vectors we have seen previously, but with the origin point being point 0 in Euclidean space.

Instead of looking for precise keyword matches, this technique examines similarities between vectors, as previously explained, enabling more accurate, semantically and contextually meaningful results, even if the words in the query are not exactly the same.

For example, "Iron Maiden," "Van Halen," and "Scorpions" are all the names of heavy metal bands. If we convert these names into tokens to create vectors, their coordinates will be similar but not identical. There will be slight differences in magnitude and direction. Therefore, they will be “orbiting” in the same “band” zone.

Conversely, "Bob Dylan" or "Genesis" will point in the opposite direction. They are still musical groups, but their styles do not have "the same direction".[

If we perform a traditional search, we must use the exact same word, which is"Music group". It will encompass all groups. However, if we want to look for a specific genre, for instance, "thrash rock", we will not know how to differentiate Metallica from Dire Straits.

In contrast, if we perform a vector search, it would locate these groups based on their proximity in both genre and musical style, showing that Metallica and Slayer are similar.

Are Vectors Really “Arrows”?

In computer science, a vector is a data structure that includes an array of numbers. In our case, these vectors store a digital summary of the dataset to which they have been applied. Consider it a summary or a digital fingerprint.

Images can also be analyzed for similarities. If you had to develop an application to compare two images, how would you do it? If you simply compared every pixel of one image with every pixel of the other, you would only find images that are identical in resolution, color, encoding, and other aspects.
However, if you could examine the images and generate vector embeddings of the content, you would be able to compare them and identify similarities. In the case of images, a vector embedding explains the content of each image and then allows for comparison.
This constitutes a much more robust method for discovering similarities between images.

A vector, speaking in computer science terms, would have a representation similar to the one below

{10,-4,6,34,0,-35,67,203,466,4,356,3,-53,-3,0}

It will be like indicating the vector's final position only, since the vector's origin is point 0.

Vector Search Algorithms

The data, which includes images, texts, audio, etc., is encoded in numerical vectors called "Embeddings". These values have varying dimensions depending on how they are encoded. The more dimensions our vector has, the more specific its definition will be, and the better it can be grouped.

Vector Similarity Searches:

We can use different types of metrics in vector similarity searches, each with its own advantages and disadvantages. The appropriate metric will depend on the data type and the application.

Euclidean Distance:

To determine if two vectors are close, we should measure the “Euclidean distance”, which is the straight-line length between two points in Euclidean space. It equals the square root of the sum of the squared differences between the point coordinates:

In an n-dimensional space, it is measured as the difference between each of the dimensions squared.

Since the value is smaller, we can deduce that the final vector points are closer to each other than the initial ones.

If we compare it with other vectors in the same space, those with the smallest values will be approximate vectors.

The distance between v1 and v3 is less than the distance between v1 and v2.

It is important to know how to calculate the distance between two points because it will be used later for measuring the magnitude of a vector.

Magnitude of a Vector

It is the distance from the vector base to its endpoint. In our case, all vectors originate at point 0, so the magnitude of a vector would be calculated using the following formula:

The data above gives us the following magnitudes of the vectors:

V1 = 5,83095189

V2 = 10

V3 = 5,6568542

Dot Product

The dot product (also called the scalar product) is an operation between two vectors that results in a real number (a scalar). It is one of the most important tools in mathematics and physics because it tells us how "aligned" two vectors are.

It is calculated by multiplying the sum of the coordinates in each dimension of the vectors to be compared.

The information from our example gives us the dot product values as follows:

Dot product v1v2 = (3 * 6) + (5 * 8) = 58

Dot product v2v3 = (6 * 4) + (8 * 4) = 56

Dot product v1v3 = (3 * 4) + (5 * 4) = 32

The larger the dot product, the greater the similarity between these two vectors.

We can say that v1 and v2 are very similar.

Cosine Similarity

This search method allows us to look for vectors not by the distance between their points, but by the angle they form.

The cosine similarity measures the orientation between two vectors in a multidimensional space, ignoring their magnitudes. It is calculated by dividing the dot product of two vectors (A) and (B) by the product of their magnitudes, resulting in a value between -1 and 1.

It is calculated using the following formula:

Following the previous example,

Similarity of the cosine of v1 and v2:
Point product v1 y v2 = (3 * 6) + (5 *8) = 18 + 40 = 58
Magnitude v1 = 5,83095189
Magnitude v2 = 10
Cosine(v1, v2) = 58 / 58,309 = 0,9947

Similarity of the cosine of v2 and v3
Point product v2 y v3 = (6 * 4) + (8 * 4) = 56
Magnitude v2 = 10
Magnitude v3 = 5,6568542
Cosine(v2, v3) = 58 / 58,309 = 0,9899

Similarity of the cosine of v1 y v3
Point product v1 y v3 = (3 * 4) + (5 * 4) = 32
Magnitude v1 = 5,83095189
Magnitude v3 = 5,6568542
Cosine(v1, v3) = 32 / 32,984 = 0,9701

We can confirm that v1 and v2 are more similar than v2 and v3, and v1 and v3.

Note: In the case of multidimensional vectors, we should perform the sum of each of the dimensions.

This approach returns vectors with similar directions, so it can help us find resemblances to make recommendations (this is how Netflix or HBO works).

In the example of music groups, we can start by searching for "thrash rock" bands. Then we can suggest other groups not categorized as thrash rock but within the heavy metal genre. That is, we start by listening to Metallica and, through suggestions, move on to Van Halen. Now you understand why Netflix might suggest watching "The Nightmare Before Christmas" after seeing "Hotel Transylvania”.

As Foghorn Leghorn once said, “It’s math, son!! The numbers don’t lie.”

How Do We Use This Mathematical Knowledge In Vector Search?

First, we need to convert our data (text, images, etc.) into a vector, as we have indicated before.

However, vectors do not create themselves. That means it is not enough just to give them a random value defined by us.

LLM models allow us to create the dot product and use cosine similarity to perform searches within InterSystems IRIS. Euclidean search is not implemented, but could be applied with Python libraries.

Some people have already thought about this because it will allow us to associate correct vectors based on the text context… Yet, I will explain this in the next article.

Note: I am sorry for the math lesson. Yet, I had to explain how it works first to help you better understand the "search magic".

The Gaia Planetarium: A Full-Stack Embedded Python Project

InterSystems Developer — Sun, 23 Aug 2026 15:26:23 +0000

If you are a regular on the developer community, you may have seen some recent posts about the InterSystems First Employee Programming competition. The challenge is simple — transform some Gaia Epoch Photometry data, calculate the percentage change of flux (between the maximum and minimum values), and output a list of the stars with a percentage change of greater than 100.

Now while this was a fun challenge, but I felt there was something missing: a lack of scope for creativity. After all, we are looking at stars! How can something as magical as the night sky be distilled down to a CSV files of IDs and flux values?

So I decided to do something different with my main entry, and visualise stars the way they should be viewed — in the night sky above us. Let's take a look at the Gaia planetarium:

Project Design

The first question was what information is needed to plot the stars in the nights sky? Now its easy to plot a point on earth - you just need a longitude and latitude. For stars, you also need two locating values, Right Ascension (RA) and Declination (Dec). Of course, it gets more complex if you want to know where they are in location to the earth, but that was solved later.

These values aren't in the Photometry datasets, instead being found in the Gaia source table, which can helpfully be queried using a Python library called astroquery. This made the decision to use Python a no-brainer.

So I decided upon the following stack:

- PyProd production
- Ingests Photometry data files
- Calculates output (and adds to csv file)
- Queries the Gaia Source table to get the location for each source ID.

- Flask Web Application (hosted using IRIS WSGI hosting):
- Query data from IRIS tables using Embedded Python
- Create REST Service to send data to the front-end

- Front-end UI with HTML/CSS/JS

Now, before going through the implementation in a bit more detail, I will detail one issue I found. The Gaia photometry data is heavy. Each zipped file is around 15.5MB, which doesn't sound like that much, until you realise there is >3000 of them. What's more, each of these files maps a small portion of the sky in immense detail, whereas I am much more interested in covering the sky with stars that could be visible to the naked-eye.

I therefore decided to add separate production components which can just query the Gaia source data, ordered by brightness to add the most visible stars to my planetarium. I've still included the photometry dataset and, because it is a production, its easy to throw more files into the watched directory to add them into map. The challenge results are available as an overlay, and may not be visible depending on whether the small portion of the sky that the photometry data maps is overhead.

I also added star data from a different dataset — Hipparcos, because many of the most visible stars overload the Gaia sensor, so are not available in the Gaia dataset. Including Hipparcos stars was important for viewing constellations to my planetarium. I also added constellation data from Stellarium to visualise the constellations in the sky.

IRIS Implementation

PyProd

I've recently written about PyProd for another example project, so I am going to skip the technical details in this case. One comment I will make though — it was really nice to be able to build a production in Python because I required a few steps which are super easy to do in Python, and not so easy in ObjectScript. The key example of this was querying the Gaia dataset directly with the astroquery.gaia library.

I also used this project as a moment to road test a new PyProd agent skill. This way, as soon as I start using PyProd, my agent can read the skill and see exact patterns of how it should be working with PyProd. A version of this skill is now available in the iris-agentic-dev skill library

The Web App: Flask

Its not super well known that IRIS can host WSGI applications, lets face it, I didn't even know what a WSGI application was when I first heard this! Web-Server Gateway Interface is a Python standard for running web applications. Some of the most popular Python web application frameworks, including Flask and Django, run on WSGI.

Flask is a lightweight framework for developing REST APIs. It has pretty simple syntax, where you define a function with a decorator to make it an REST endpoint. Combining this with Embedded Python makes it easy to get data from IRIS. For example, a simplified version of the endpoint which collects stars from the IRIS table is as follows:

from flask import Flask, request

import iris # Embedded python IRIS import 

app = Flask(name, static_folder="/home/irisowner/dev/src/skymap/static)


  
  
  Endpoint to access stars from the Database


@app.route("/api/stars", methods=["GET"])

def get_stars() 

    # SQL Query 

    query = """

        SELECT TOP 1000 SourceId, Ra, DecDeg, PhotGMeanMag 

        FROM "Gaia.SourceLocation"

        """

# Execute query 
rows = iris.sql.exec(query)

# Collect results
output = [] 
for row in rows: 
    output.append({
      "source_id": row[0],
        "ra"     : row[1],
        "dec"    : row[2],
        "mag"    : row[3]
    })

# Return results
return output

And we can also use this to activate a PyProd adapterless Business Service:

from intersystems_pyprod import director 


  
  
  POST endpoint


@app.route("/api/more-stars", method=["POST"])

def add_stars(): 

    # Get the info from the post request

    n_stars = int(request.args.get("n_stars"))

# Create Business Service
status, service = director.create_business_service("Gaia.StarCatalogService")

# Activate Business Service
service.process_input(n_stars)

Flask hosting

WSGI applications can be hosted through the Management Portal at System -> Security -> Applications:

But I wanted to do this programatically through Embedded Python. Using the Security.Applications.Create() function required me passing an IRIS array by reference into the function, which can be achieved using an iris.arrayref(<python dict>):

import iris
# Define settings 
props = iris.arrayref({
            'Type': 2,
            'NameSpace': 'USER',
            'WSGIAppLocation': '/home/irisowner/dev/src', # Path to flask project
            'WSGIAppName': 'skymap.server', # FolderName.FileName (without .py)
            'WSGICallable': 'app',
            'WSGIDebug': 0,
            'WSGIType': 1,
            'AutheEnabled': 64,
            'Enabled': 1,
            'Description': 'Gaia sky map Flask/WSGI application',
            "DispatchClass":"%SYS.Python.WSGI", # Needed for WSGI hosting
            "Path":"/home/irisowner/dev/src", # Path to flask project
            "WSGIDebug": 1, # Refresh when the code changes
            "MatchRoles": ":%All" # Security roles
        })

# Create Web App
sc = iris.Security.Applications.Create('/skymap', props)

An easy point to miss here if you normally create WSGI applications through the management portal: you need to set the DispatchClass to "%SYS.Python.WSGI".

Front-end

Unlike a pure Python framework like Streamlit, Flask include a Python front-end framework, instead relying on building a front-end with HTML/CSS/JavaScript (or some front-end framework).

I'm going to skip most of the details on this because it was largely a question of me describing clearly what I wanted, and getting some AI generated code as a result.

It is pure HTML/JS/CSS, which I personally am a big fan of. I know it has limits, but sometimes I think starting with a front-end framework overcomplicates things.

The Front end is hosted in the Flask app through a static route:

from flask import Flask, jsonify, request, send_from_directory

STATIC_DIR = os.path.join(os.path.dirname(__file__), "static")
app = Flask(__name__, static_folder=STATIC_DIR)

@app.get("/")
def index():
        return send_from_directory(STATIC_DIR, "index.html")

The only other thing to mention is that Cross Origin Resource Sharing is also handled from Flask

@app.after_request
def add_cors(response):
        response.headers["Access-Control-Allow-Origin"] = "*"
        return response

Conclusion

As I mentioned at the start of this article, this project started out as a competition entry for the Employee Programming Competition. However, it quickly spiralled into something else, once I realised the limitations of only using the Gaia Photometry Data. It has become a Python Full Stack Application, which integrates multiple data sources (Gaia, Hipparcus and files of constellations and star names).

To be clear though, it still does what was asked by the competition, and it even plots it as a bright yellow/orange/red patch (coloured by magnitude of flux change) of sky which is covered by the Photometry data. So if you've made it this far, please consider voting for my planetarium in the community vote!

I hope you've enjoyed reading about this Embedded Python project as much as I've enjoyed making it!

iris-agentic-dev -- Give Your AI a Live Connection to IRIS, Part 1: The Problem, the Tool, and Getting Started

InterSystems Developer — Thu, 13 Aug 2026 09:35:07 +0000

Part 1 of a series. Part 2 covers the full tool catalog. Part 3 covers ObjectScript skills. Part 4 covers benchmarking and measuring what actually improves.

The Problem Hiding in the Comments

Thomas Mazur's post "Frogs, Chickens, AI, and VS Code" on VS Code productivity — Peacock, scoped workspace files, Copilot Agent mode — drew a sharper problem in the comments. Pietro Di Leo and Mike.W pointed out that when you work server-side in VS Code, the isfs:// workspace most production IRIS shops use, Copilot can only see the files open in your editor. It cannot index the virtual filesystem. On a mature IRIS application with thousands of classes, the AI works through a keyhole.

John Murray pointed people at a project I've been building — iris-agentic-dev — and noted no Developer Community article existed for it yet. So here it is: why the problem exists, how the tool addresses it, and how to get it running in about five minutes.

Why the AI Can't See Your Namespace

When you open an isfs:// workspace, your IRIS classes live on the server, not on disk. The VS Code ObjectScript extension streams them to you on demand via the Atelier API — open a class, it fetches it; save it, it writes back. This works beautifully for editing.

AI assistants such as Copilot work differently. They need a picture of the code around the file you're editing. Who calls this method? What inherits from this class? What other code touches this global? On a local project, the assistant can scan the files to answer those questions. An isfs:// workspace materializes files only when you open them, so there is nothing complete to scan.

For a new project with a handful of classes, that may be tolerable. For a production IRIS system — ten thousand classes, Ensemble productions, custom %Library subclasses, business logic accumulated across years of development — the AI becomes nearly useless for the hard questions. It can help you write a new method if you paste in the surrounding context yourself. It cannot help you understand the system.

Give the AI a different kind of connection, one that can ask IRIS directly instead of crawling the disk.

What iris-agentic-dev Is

iris-agentic-dev is an MCP server — a background process that gives AI assistants a set of tools they can call to interact with a live IRIS instance. It works with GitHub Copilot (via the VS Code extension), Claude Code, Cursor, and OpenCode. The IRIS instance can run natively on Windows or Linux, or in Docker.

Once configured, the MCP server's tools are available directly from chat. VS Code 1.99 and later support MCP for Copilot Agent mode; Claude Code and OpenCode have supported it since launch.

iris-agentic-dev connects to IRIS through the same Atelier REST API used by the ObjectScript extension. The assistant can then:

Search the entire namespace — full-text, regex, by category, without opening anything
Compile classes and get errors back with line numbers
Run ObjectScript and see the output
Execute SQL queries against any namespace
Introspect class definitions — properties, methods, parameters, inheritance chains
Inspect Ensemble productions — which items are running, what's wired to what, message bodies, business rule logic, and drift between the running config and source control
Run unit tests and report results
Debug — map INT line numbers back to original source lines, pull error logs

Part 2 covers the complete tool catalog. Instead of guessing from a few open tabs, the assistant can ask IRIS about the namespace itself.

---

Built With the Community

I started the project after running into this limitation repeatedly in my own IRIS work. Community contributions have shaped it since — often from the same people who show up more than once. John Murray, who pointed people at this project in the Frogs and Chickens thread, also built the Server Manager authentication integration you'll use in Step 2 below: instead of typing credentials into a config file, the MCP server reads them straight from the OS keychain through the same AuthenticationProvider the Server Manager extension itself uses. Dorian TETU has contributed fixes across search accuracy, source control elicitation, and surgical-edit diffs.

The project is open source under the intersystems-community GitHub organization. Contributions and bug reports are welcome, including "It doesn't work on my setup."

Getting Started: VS Code + GitHub Copilot

If you already use VS Code with the InterSystems ObjectScript extension, this is the fastest path.

Prerequisites: VS Code, GitHub Copilot subscription, and the InterSystems ObjectScript extension (which you almost certainly already have).

Step 1 — Install the VS Code extension

Search for iris-agentic-dev in the VS Code Marketplace and install it. On first activation, the extension locates or downloads the MCP server binary: if you already have it on PATH (e.g. via brew install iris-agentic-dev), it uses that; otherwise it downloads the right binary for your platform automatically. Either way, it registers itself with Copilot — no manual wiring required.

The iris-agentic-dev tool set appears in Copilot's Agent mode after installation.

Step 2 — Verify the connection

Open Copilot Chat and switch to Agent mode. Ask:

"Call check_config and show me the result."

You should see your IRIS connection details — host, port, namespace, Atelier API version. If the InterSystems Server Manager extension is installed, iris-agentic-dev finds your server configuration and retrieves credentials from the OS keychain automatically. The VS Code extension follows the active objectscript.conn, so developers with several Server Manager entries keep using the connection selected for that workspace. When running the MCP server outside the VS Code extension, set IRIS_SERVER_NAME to the corresponding key from intersystems.servers if more than one server is configured. The check_config result shows which connection is active and which other servers were detected.

check_config confirms the IRIS host, port, namespace, and connection source Copilot is using.

Step 3 — Ask something that requires the whole namespace

Now try a question that would be difficult to answer from open tabs alone:

"Search for all classes in this namespace that extend %Persistent. How many are there?"

"What are the properties and methods on MyApp.SomeClass?"

"Compile MyApp.*.cls and show me any errors."

None of these requires you to open the relevant files first. The assistant gets the answers from IRIS.

Getting Started: Claude Code

Install the binary (Mac):

brew tap intersystems-community/tap
brew install iris-agentic-dev

Or download directly from the releases page for Mac Intel, Linux, or Windows.

Configure the connection. Create ~/.iris-agentic-dev.toml:

host = "localhost"
web_port = 52773
username = "_SYSTEM"
password = "SYS"
namespace = "USER"

Register with Claude Code:

claude mcp add --scope user iris-agentic-dev -- iris-agentic-dev mcp

Then verify:

> Call check_config and show me the result.

Example: How iris-agentic-dev tools support analyzing an IRIS Interoperability application

Here is a real exchange against the irisdemo-demo-readmission production — a health interop demo that processes hospital discharge events and scores patients for readmission risk.

"How does an ADT A03 discharge message flow through this production?"

Step 1: find what's compiled.

iris_symbols("IRISDemo.*")
→ 31 classes: BO.*, BP.*, BS.*, DTL.*, Util.*, and more

Key classes: IRISDemo.BP.ReadmissionRisk.Process, IRISDemo.DTL.HL7Discharge, IRISDemo.DTL.HL7Update, IRISDemo.HISHL7v2FileFeedRoutingRule.

Step 2: find the router's rule.

extract_message_map_routing("IRISDemo.HISHL7v2FileFeedRoutingRule")
→ NOT_FOUND — Ens.Rule.Definition, not a routing table class

Ens.Rule.Definition classes hold routing logic in XData. The tool can't map that structure, so read the class source directly:

iris_doc("IRISDemo.HISHL7v2FileFeedRoutingRule.cls") → XData rules:
  Rule 1: docName=ADT_A01 or ADT_A08  → transform DTL.HL7Update, target Readmission Risk Process
  Rule 2: docName=ADT_A03             → transform DTL.HL7Update, target Readmission Risk Process

A03 discharges go through IRISDemo.DTL.HL7Update, which stamps UpdateMessageType="A03" on the request — that field is what lets the business process branch differently for discharges vs. admits.

Step 3: map the business process.

extract_message_map_routing("IRISDemo.BP.ReadmissionRisk.Process")
→ kind: bpl, 4 outbound calls:
    Update Encounter          → LACE SOAP Operation
    Calculate Risk with LACE  → LACE SOAP Operation
    Calculate Risk with ML    → Readmission ML Model Consumer
    EMR Readmission Update    → HisDB Encounter Update Operation

Step 4: get the full step tree.

docs_introspect("IRISDemo.BP.ReadmissionRisk.Process") → xdata_flow:
  Call:  Update Encounter          → LACE SOAP Operation
  Call:  Calculate Risk with LACE  → LACE SOAP Operation
  Call:  Calculate Risk with ML    → Readmission ML Model Consumer
  Call:  EMR Readmission Update    → HisDB Encounter Update Operation  [async]
  If:    Discharge OK?
           (request.UpdateMessageType = "A03") && (context.UpdateEncounterResult = 1)
    If:  Risk Alert?
           (context.RiskScore > 11) || (context.MLReadmissionRisk > 0.15)
      assign: Compose Alert Message
      Call:  Add Patient to Risk Program  → Care Team  [async]
      Call:  Alert Care Team              → Risk Alert Email Operation
      sync:  Follow up SLA 2 days
      If:    No follow up?  (synctimedout)

The session also flagged that IRISDemo.DTL.HL7Discharge exists and maps 9 HL7 fields to a DischargeRequest — but the routing rule never sends A03 through it. Dead code, spotted without opening a file.

The full exchange — every tool call, response, and reasoning step — is in this GitHub Gist.

In four steps the assistant answered the question: A03 discharges hit the router, get transformed into an UpdateEncounterRequest with the trigger event stamped as the branch signal, and the business process runs LACE and ML risk scoring in sequence — alerting the care team and starting a 2-day follow-up if either score exceeds the threshold. No files were open. Everything came from IRIS.

What's in the Next Parts

Part 2 — The Tools: A practical walkthrough of the tool catalog: what each tool does, when to use it, and which IRIS-specific problems it solves. The search, introspection, and Ensemble tools are especially useful for questions that open editor buffers cannot answer.

Part 3 — Skills: A live connection does not fix an AI model's weak grasp of ObjectScript: subtle syntax differences, %Status propagation, $$$ macros, and COS-specific idioms that are scarce in general training data. Skills are short instruction files that target these weaknesses. On my 22-task ObjectScript repair suite, a 205-word checklist called objectscript-review took the pass rate from 73% to 100% against Claude Sonnet 4.6 — a single run on a small public suite, with all the caveats that implies. Part 3 covers what the skills do; Part 4 covers how much to trust the number.

Part 4 — Benchmarking: How the benchmark harness works, how to run it, and what the numbers mean. That includes where skills help, where they have no effect, and at least one that appears to hurt performance when loaded globally — more instructions are not always better. It also covers the limits of a suite this size: contamination risk from public tasks, single-run variance, and why a lift measured on one model says little about another.

AI-Assisted Development on IRIS: Beginner tips and guidance

InterSystems Developer — Thu, 13 Aug 2026 09:32:54 +0000

This article provides an AI agent-agnostic view of developing with AI coding assistants, with an IRIS-specific focus. This guidance is based on standards that can be used whether you use Claude Code, GitHub Copilot, Codex, or one of the other coding agents. As such, it doesn't cover setup instructions. Instead, it covers key concepts and how they have improved the performance of AI for my work.

Hi everyone, I wanted to share some thoughts, advice and examples of using AI for IRIS development. Before starting though, I have lots of opinions on AI, far more than I can fit in this article. I am not an AI evangelist. I started as a skeptic and still hold on to a lot of skepticism, along with an intense dislike for slop. I am, however, an absolute believer in the ability of these tools if you can learn to use them correctly.

I use AI regularly, but make a conscious effort to follow, understand and review any code that isn't a toy project or personal tool. My opinions on AI coding softened dramatically when I first tried vibe-coding for a personal tool (a presentation app which displays web-pages directly alongside slides) and was amazed by success. I recommend next time you think "I wish I had an application/vs code extension/tool which does x", try asking an AI agent for it.

Of course, the correct approach will vary for each user and each scenario. People working with sensitive data in production database should be far more careful about using AI than I am creating demo projects in isolated containers. As such, I can't claim my experience will be the same as anyone else, but I do suggest taking some time to explore approaches that might work for you.

"I tried using AI to write ObjectScript but it hallucinated all the methods"

AI agents have improved a lot, even since I started at InterSystems in September 2025. Developer circles often talk about the November inflection point where the release of Claude Opus 4.5 and GPT-5.2 changed the game with agentic coding. Suddenly models had the ability (and context window) to chain together tool calls to develop, reason, and fix bugs. These models have been incrementally improving with each release cycle since and may well continue to do so.

In this time, ObjectScript coding from LLMs has improved dramatically. I recommend you re-evaluate any belief about the ability of AI in coding matters that pre-dates these releases, and try again with one of the latest (and most powerful) models in a coding harness.

Improving your agent's skillset

Frontier AI models (and their lesser counterparts) have a pretty good very good knowledge of most matters, essentially because they have consumed the entire internet. It is true that their ObjectScript knowledge is often less than other languages, primarily because there is less ObjectScript available on the web than other languages.

This is where agent skills come in.

Skills are markdown files with some YAML front-matter, it's (basically) that simple. In the metadata, you give the skill a name, and a description, which crucially should say when an agent should use the skill. The name and description are loaded into the agent's context window, and when they need the specific guidance the skill provides, they can activate the skill and use the markdown contents. This is great for specific knowledge, or advice, for example on a lesser used part of a coding language they are a bit ropey at.

iris-agentic-dev, the MCP server that @tomd recently shared with the community includes a skill library. One of the skills, @timothy.Leavitt's objectscript-review, only includes a checklist of the 10 most common ObjectScript errors, and yet dramatically includes benchmark performance. This skill obviously required extensive ObjectScript knowledge in the first place, alongside experience reviewing agent written ObjectScript to know the most common mistakes. But the benefit is the agent should now correct these mistakes itself, and the future code it produces will be better as a result.

Skills are reusable pockets of information. If you have a repeatable task an agent struggles with, let it struggle the first time, then when it gets to the right answer (maybe with your guidance) say "write a skill that covers the mistakes you've made here". I recommend reviewing and editing the generated skills carefully because agents tend to put in project specific information which doesn't generalise. But as long as the problems can be generalisable, the solutions can be reusable. Next time, the agents won't make the same mistakes (...probably, there's no certainty with non-deterministic models).

Improving your agent's toolset

Skills are great to prevent repeated errors, but they don't help the agent actually do things for you. This is where tools come in. Tools, in the context of AI agents, are functions which the agent can call using structured (JSON) responses. The standard protocol for adding tools to agents is the Model Context Protocol (MCP). This has been written about extensively on the community including articles by me, Pietro Di Leo and Tom. I will also once again plug this great intro video from InterSystems President Don Woodlock.

MCP servers can be used to expose business logic to external agents or connectors (see my introduction to MCP servers in AI Hub). However, to date at least, MCP servers are most commonly used as developer tools. This is the context I want to discuss here.

If you tell an LLM to write some ObjectScript using an obscure class, it will likely hallucinate how a statistically average version of how the class might look. Instead, if you give an agent with access to a tool to search the class reference documentation, it will likely look up the proper syntax before writing. If you give it access to an ObjectScript shell (or execution environment), it may even test the function syntax before writing.

Try to imagine you were asked to code something from scratch using an obscure library and think about what you would need to do a good job. It would probably include documentation and a feedback loop to test the code you've written. Coding agents require exactly the same.

This is the value of MCP servers. Agents can autonomously search for proper syntax, test functions and code, and try to compile classes. When they see an error, they can read the error trace and investigate. They can execute more code to find the bugs, and search for other classes for proper syntax.

iris-agentic-dev is an MCP server which provides many, many tools to do different functions in IRIS. If you are a system administrator managing multiple IRIS servers, it has tools to view and edit the roles, servers and logs. If you are a developer, the tools to execute ObjectScript, search existing classes or read production logs, might be more relevant to you.

Customisation

Many people have their own golden rules for using AI coding agents, like "tests are essential", "create and review specification docs before touching code", "always review the output", "anything intended to be read by a human should be written by a human". These are all valid (and good advice), but for me, there's one golden rule that is more important.

Customisation is key.

For agents to be useful for your use case, they need to be customised to your use case. Let's look at some ways to do this.

Skills

Skills are a great way to customise. I have a library of agent skills to cover my own preferences. For example I have skills make code more readable, to write check scripts for interactive tutorials, and to use PyProd to write productions in Python (this one has made it into iris-agentic-dev's skill library).

I also have skills which other's have recommended, e.g. obra/superpowers, that have been customised to my preferences. They are just markdown files after all. Take the bits you like, and add/remove sections to get the instructions right for your work.

iris-agentic-dev

For iris-agentic-dev, this customisation may come in the form of restricting tools that aren't generally useful to you with the IRIS_DISABLED_TOOLS argument. For example, I have turned off server-side source control tools because I always do source control on the client side, and otherwise agents see it and think that means they should use it. I've also turned off the system admin tools because 95% of my IRIS usage is done with SuperUser so role management is totally not required for my use case. For others, managing different users and using server-side source control will be incredibly valuable whereas giving an agent execution power might be too risky, so they might make the opposite decisions.

I've also created custom iris-agentic-dev instructions in the form of a skill, with the description "Use this skill when you want to connect to a running IRIS instance". This skill includes the line VS CODE COMPILES THE CLASS ON SAVE, YOU DO NOT NEED TO MANUALLY COMPILE CLASSES, because I've watched agents go in circles trying to copy a file into a docker container then compile it, only to find out its "suspiciously" already up-to-date. This use case-specific customisation informed by watching agents proves valuable in the long term.

AGENTS.MD

Finally, you can also customise your agents with AGENTS.MD (or CLAUDE.MD) files, either at a project root or the global config. The contents of these are automatically sent to the agent with every new conversation.

Project AGENTS.MD are good for project specific information, e.g. This project does x, the source files are in ./src/package, port 52773 on IRIS is mapped to port 62783. That way, each new conversation I have with an agent doesn't require an introduction, and the agent doesn't have to search through the whole project to find the relevant files.

Global versions are for rules you want the agent always to abide, for example my global CLAUDE.MD includes NEVER USE EMOJIS ANYWHERE NOT EVEN TICK MARKS about 3 times. I've also included some more useful guidance, e.g. Give a (very brief) explanation of tool calls or series of tool calls to ensure I can follow what you are trying to do.

Conclusions

For any customisation, you need to try using agents. See what works and what doesn't, what an agent is good at and bad at. If an agent does something you don't like, add instructions not to do it again in one of the places mentioned above.

Finally, in order to customise, you also need to know what your use case requires. You need to learn with the agent and know what you are directing the agent to do. There are times when letting the agent run autonomously is incredibly powerful, but in general, I prefer keeping a close eye on what the agent is doing, learning from the outputs, and course-correcting when it inevitably does something stupid.

Final notes

This article has been long, opinionated, and maybe a touch ramble-y, but I hope it has been interesting to some readers. If you would like to hear more on these topics, on opinionated guidance for using AI-assisted coding, or just need help getting started with skills, agents or iris-agentic-dev, feel free to reach out in the comments.

Building a Pure Python Healthcare Interoperability Production with PyProd and the openFDA API

InterSystems Developer — Fri, 31 Jul 2026 20:45:47 +0000

Hi Developers!

In my previous article, Electric Utility PyProd, we built a simple interoperability production that processed CSV files from a local directory using the PyProd framework. While that example introduced the basic building blocks of a production implemented entirely in Python, real-world interoperability solutions often need to communicate with external systems.

In this article, we'll build a more advanced production that retrieves healthcare data from the public openFDA Drug Adverse Event API, analyzes the returned data, and stores healthcare analytics in InterSystems IRIS.

Along the way, we'll see how to:

call an external REST API from a PyProd Inbound Adapter
work with large JSON payloads efficiently
perform batch-level healthcare analytics
persist the results in an IRIS SQL table
implement an entire interoperability production using only Python

Setting up

Clone the repository:

git clone https://github.com/Gra-ach/openfda-healthcare-pyprod.git

cd openfda-healthcare-pyprod

Start the container:

docker-compose up --build -d

Once the container is running, load the production:

intersystems_pyprod src/healthcare-openfda-pyprod/openfda_adverse_events.py

Step 1 – Create the Inbound Adapter

Unlike the previous example, this production doesn't wait for files to appear in a directory. Instead, the custom OpenFDAInboundAdapter periodically connects to the public openFDA Drug Adverse Event API. Rather than querying the same medication every time, the adapter rotates through a configurable list of common medications:

ASPIRIN

IBUPROFEN

ACETAMINOPHEN

NAPROXEN

LORATADINE

Each polling cycle:

selects the next medication
builds the REST query
downloads the latest adverse-event reports
saves the response as a JSON file
sends a lightweight production message

Saving the payload to disk instead of passing it through the production keeps messages small and avoids IRIS string-size limitations.

class OpenFDAInboundAdapter(InboundAdapter):
    api_base_url: str = IRISProperty(
        description="openFDA Drug Adverse Event API URL",
        settings="API Settings"
    )
    result_limit: int = IRISProperty(
        description="Number of records to retrieve per poll",
        settings="API Settings"
    )
    api_key: str = IRISProperty(
        description="Optional openFDA API key",
        settings="API Settings"
    )
    payload_dir: str = IRISProperty(
        description="Directory where raw openFDA JSON payloads are saved",
        settings="File Settings"
    )
    medication_names: str = IRISProperty(
        description="Comma-separated medication names to rotate through",
        settings="API Settings"
    )  

    def on_task(self):
        os.makedirs(self.payload_dir, exist_ok=True)

        meds = [
            med.strip().upper()
            for med in str(self.medication_names or "").split(",")
                if med.strip()
        ]

        if not meds:
            meds = ["ASPIRIN", "IBUPROFEN", "ACETAMINOPHEN", "NAPROXEN", "LORATADINE"]

        state_file = f"{OPENFDA_ROOT}/last_med_index.txt"
        os.makedirs(OPENFDA_ROOT, exist_ok=True)

        try:
            with open(state_file, "r", encoding="utf-8") as f:
                last_index = int(f.read().strip())
        except Exception:
            last_index = -1

        next_index = (last_index + 1) % len(meds)
        selected_med = meds[next_index]

        with open(state_file, "w", encoding="utf-8") as f:
            f.write(str(next_index))

        search_query = f'patient.drug.medicinalproduct:"{selected_med}"'

        params = {
            "search": search_query,
            "limit": int(self.result_limit or 50),
            "sort": "receiptdate:desc",
        }
        if self.api_key:
            params["api_key"] = self.api_key

        url = f"{self.api_base_url}?{urllib.parse.urlencode(params)}"
        pulled_at = datetime.utcnow().isoformat(timespec="seconds")
        safe_timestamp = pulled_at.replace(":", "").replace("-", "")
        pulled_at = pulled_at.replace("T", " ")
        payload_file_path = os.path.join(
            self.payload_dir,
            f"openfda_adverse_events_{safe_timestamp}.json",
        )

        IRISLog.Info(f"Calling openFDA API: {url}")

        try:
            with urllib.request.urlopen(url, timeout=30) as response:
                payload_bytes = response.read()

            with open(payload_file_path, "wb") as payload_file:
                payload_file.write(payload_bytes)
        except Exception as ex:
            IRISLog.Error(f"openFDA API call or payload write failed: {ex}")
            return Status.Error()

        msg = AdverseEventFileMessage(
            api_url=url,
            search_query=search_query,
            pulled_at=pulled_at,
            payload_file_path=payload_file_path,
            medicine = selected_med
        )
        self.business_host_process_input(msg)
        return Status.OK()

We can see the events in the log for the inbound adapter, each time info about a different medicine is requested:

![ ](https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/yben0tbb988bqfkld7xd.png)

Step 2 – Create the Business Service

The Business Service is intentionally simple. Its only responsibility is forwarding the metadata produced by the adapter to the Business Process.

Notice that we're no longer passing the entire JSON document between production components. The message AdverseEventFileMessage that is forwarded between the OpenFDAEventService and OpenFDAAnalysisProcess contains only:

API URL
search query
selected medication
timestamp
payload file path

class AdverseEventFileMessage(JsonSerialize): 
    api_url: str = Column() 
    search_query: str = Column() 
    pulled_at: str = Column() 
    payload_file_path: str = Column() 
    medicine: str = Column()

This keeps production efficient while preserving access to the original API response.

class OpenFDAEventService(BusinessService): 
    ADAPTER: str = IRISParameter( 
        value="HealthOps.OpenFDAInboundAdapter", 
        description="Pure Python CSV polling adapter" 
    ) 
    process_target: str = IRISProperty( 
        description="Business process target", 
        settings="Target Settings" 
    ) 

    def on_process_input(self, input): 
        return self.send_request_async(self.process_target, input)

Here are the messages in the Message Viewer:

![ ](https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/bx3sbri80t9ugrl041q4.png)

Step 3 – Create the Business Process

The Business Process performs the analytics. Using the payload file path, it reloads the JSON response and analyzes the complete batch of adverse-event reports.

For every API batch it calculates:

total number of reports
serious adverse-event count
serious adverse-event percentage
death count
hospitalization count
average patient age
most frequently reported reaction

Unlike the Electric Utility example, which generated one database row per input record, this production generates one analytics message representing the entire batch.

This greatly reduces message traffic while still preserving all meaningful statistics.

class OpenFDAAnalysisProcess(BusinessProcess): 
    operation_target: str = IRISProperty( 
        description="Operation that persists rows and analysis results", 
        settings="Target Settings" 
    ) 

    def _age_to_years(self, age_value, age_unit) -> Optional[float]: 
        if age_value in ("", None): 
            return None 
        try: 
            age = float(age_value) 
        except Exception: 
            return None 
        unit = str(age_unit or "") 
        if unit == "801": 
            return age 
        if unit == "802": 
            return age / 12.0 
        if unit == "803": 
            return age / 52.0 
        if unit == "804": 
            return age / 365.0 
        if unit == "805": 
            return age / 8760.0 
        return age 

    def _load_records(self, payload_file_path: str): 
        with open(payload_file_path, "r", encoding="utf-8") as payload_file: 
            payload = json.load(payload_file) 
        return payload.get("results", []) 

    def on_request(self, request): 
        try: 
            records = self._load_records(request.payload_file_path) 
        except Exception as ex: 
            IRISLog.Error(f"Failed to read openFDA payload file {request.payload_file_path}: {ex}") 
            return Status.Error() 

        record_count = len(records) 
        serious_count = 0 
        death_count = 0 
        hospitalization_count = 0 
        ages: List[float] = [] 
        reaction_counts: Dict[str, int] = {} 

        for record in records: 
            if str(record.get("serious", "")) == "1": 
                serious_count += 1 
            if str(record.get("seriousnessdeath", "")) == "1": 
                death_count += 1 
            if str(record.get("seriousnesshospitalization", "")) == "1": 
                hospitalization_count += 1 

            patient = record.get("patient", {}) or {} 

            age_years = self._age_to_years( 
                patient.get("patientonsetage"), 
                patient.get("patientonsetageunit"), 
            ) 
            if age_years is not None: 
                ages.append(age_years) 

            for reaction in patient.get("reaction", []) or []: 
                term = reaction.get("reactionmeddrapt") 
                if term: 
                    reaction_counts[term] = reaction_counts.get(term, 0) + 1 

        serious_rate_pct = round((serious_count / record_count) * 100, 2) if record_count else 0.0 
        avg_patient_age_years = round(sum(ages) / len(ages), 2) if ages else 0.0 

        top_reaction = "" 
        top_reaction_count = 0 
        if reaction_counts: 
            top_reaction, top_reaction_count = max(reaction_counts.items(), key=lambda item: item[1]) 

        analysis = AdverseEventAnalysisMessage( 
            api_url=request.api_url, 
            search_query=request.search_query, 
            pulled_at=request.pulled_at, 
            payload_file_path=request.payload_file_path, 
            record_count=record_count, 
            serious_count=serious_count, 
            serious_rate_pct=serious_rate_pct, 
            death_count=death_count, 
            hospitalization_count=hospitalization_count, 
            avg_patient_age_years=avg_patient_age_years, 
            top_reaction=top_reaction, 
            top_reaction_count=top_reaction_count, 
            medicine = request.medicine 
        ) 

        IRISLog.Info( 
            f"Batch analysis complete: " 
            f"medicine={request.medicine}, " 
            f"records={record_count}, " 
            f"serious={serious_count}, " 
            f"serious_rate={serious_rate_pct}%, " 
            f"deaths={death_count}, " 
            f"hospitalizations={hospitalization_count}, " 
            f"avg_age={avg_patient_age_years}, " 
            f"top_reaction={top_reaction}" 
        ) 

        return self.send_request_async(self.operation_target, analysis, response_required=0)

Here we can see the incoming and outgoing messages for the Business Process:

Here's the trace of messages for the whole cycle:

The message AdverseEventAnalysisMessage contains aggregated info about the received info about the concrete medicine:

class AdverseEventAnalysisMessage(JsonSerialize): 
    api_url: str = Column() 
    search_query: str = Column() 
    pulled_at: str = Column() 
    payload_file_path: str = Column() 
    record_count: int = Column() 
    serious_count: int = Column() 
    serious_rate_pct: float = Column() 
    death_count: int = Column() 
    hospitalization_count: int = Column() 
    avg_patient_age_years: float = Column() 
    top_reaction: str = Column() 
    top_reaction_count: int = Column() 
    medicine: str = Column()

And here's the log of the Business Process with the results of calculations:

Step 4 – Create the Business Operation

The Business Operation receives the batch analysis and stores it in InterSystems IRIS. If the SQL table doesn't exist yet, it is created automatically.

Each API request produces one row containing:

medication name
search query
API URL
payload file path
number of retrieved reports
serious-event statistics
hospitalization statistics
average patient age
top reported reaction

Once the insert succeeds, the JSON payload is moved into the archive directory.

class OpenFDADBOperation(BusinessOperation): 
    archive_payload_dir: str = IRISProperty( 
        description="Directory where successfully processed JSON payloads are archived", 
        settings="Operation Settings" 
    ) 

    message_map = { 
        f"{iris_package_name}.AdverseEventAnalysisMessage": "save_events" 
    } 

    def _ensure_table(self): 
        ddl = """ 
        CREATE TABLE IF NOT EXISTS HealthOps.OpenFDAAdverseEvents ( 
            id INTEGER IDENTITY PRIMARY KEY,             
            payload_file_path VARCHAR(1000), 
            api_url LONGVARCHAR, 
            search_query VARCHAR(1000), 
            pulled_at TIMESTAMP, 
            batch_record_count INTEGER, 
            batch_serious_count INTEGER, 
            batch_serious_rate_pct NUMERIC(6,2), 
            batch_death_count INTEGER, 
            batch_hospitalization_count INTEGER, 
            batch_avg_patient_age_years NUMERIC(10,2), 
            batch_top_reaction VARCHAR(255), 
            batch_top_reaction_count INTEGER, 
            medicine VARCHAR(60), 
            inserted_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP 
        ) 
        """ 
        iris.sql.prepare(ddl).execute()     
    
    def save_events(self, request): 
        self._ensure_table()       

        insert_sql = """ 
        INSERT INTO HealthOps.OpenFDAAdverseEvents ( 
            payload_file_path, 
            api_url, search_query, pulled_at, batch_record_count, 
            batch_serious_count, batch_serious_rate_pct, batch_death_count, 
            batch_hospitalization_count, batch_avg_patient_age_years, 
            batch_top_reaction, batch_top_reaction_count, medicine 
        ) 
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) 
        """ 

        stmt = iris.sql.prepare(insert_sql) 
        
        stmt.execute( 
            request.payload_file_path, 
            request.api_url, 
            request.search_query, 
            request.pulled_at, 
            int(request.record_count), 
            int(request.serious_count), 
            float(request.serious_rate_pct), 
            int(request.death_count), 
            int(request.hospitalization_count), 
            float(request.avg_patient_age_years), 
            request.top_reaction, 
            int(request.top_reaction_count), 
            request.medicine 
        ) 
        
        os.makedirs(self.archive_payload_dir, exist_ok=True) 
        archive_path = os.path.join(self.archive_payload_dir, os.path.basename(request.payload_file_path)) 
        try: 
            os.replace(request.payload_file_path, archive_path) 
        except Exception as ex: 
            IRISLog.Warning( 
                f"Inserted records but could not archive payload file {request.payload_file_path}: {ex}" 
            ) 

        IRISLog.Info( 
            f"Inserted info about {request.medicine}: " 
            f"serious_rate={request.serious_rate_pct}%, " 
            f"death_count={request.death_count}, " 
            f"hospitalization_count={request.hospitalization_count}, " 
            f"avg_age={request.avg_patient_age_years}, " 
            f"top_reaction={request.top_reaction}" 
        ) 
        return Status.OK()

Here's the log of the Business Operation:

![ ](https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/xt1y9jjnlei5kkg50es2.png)

Step 5 – Define the Production

As with the previous example, the entire production is assembled directly in Python. It consists of:

OpenFDAInboundAdapter
        ↓
OpenFDAEventService
        ↓
OpenFDAAnalysisProcess
        ↓
OpenFDADBOperation

Because everything is defined in Python, no manual production configuration is required after loading the project.

class OpenFDAHealthcareProduction(Production): 
    services = [ 
        ServiceItem( 
            "OpenFDAEventService", 
            "HealthOps.OpenFDAEventService", 
            host_settings={"process_target": "OpenFDAAnalysisProcess"}, 
            adapter_settings={ 
                "api_base_url": "https://api.fda.gov/drug/event.json", 
                "medication_names": "ASPIRIN,IBUPROFEN,ACETAMINOPHEN,NAPROXEN,LORATADINE", 
                "result_limit": 30, 
                "api_key": "", 
                "payload_dir": f"{OPENFDA_ROOT}/payloads" 
            } 
        ) 
    ] 
    processes = [ 
        ProcessItem( 
            "OpenFDAAnalysisProcess", 
            "HealthOps.OpenFDAAnalysisProcess", 
            host_settings={"operation_target": "OpenFDADBOperation"} 
        ) 
    ] 
    operations = [ 
        OperationItem( 
            "OpenFDADBOperation", 
            "HealthOps.OpenFDADBOperation", 
            host_settings={"archive_payload_dir": f"{OPENFDA_ROOT}/archive"} 
        ) 
    ]

Step 6 – Run the Production

Start the production:

python controls.py start HealthOps.OpenFDAHealthcareProduction

Or from the IRIS terminal:

zn "ENSEMBLE"
do ##class(Ens.Director).StartProduction("HealthOps.OpenFDAHealthcareProduction")

Or in the UI in Management Portal:

Every polling cycle automatically selects the next medication and downloads a fresh batch of adverse-event reports.

Results

The production stores one summary row for every API call. For example:

SELECT
    medicine,
    batch_record_count,
    batch_serious_rate_pct,
    batch_death_count,
    batch_hospitalization_count,
    batch_avg_patient_age_years,
    batch_top_reaction
FROM HealthOps.OpenFDAAdverseEvents
ORDER BY inserted_at DESC

This makes it easy to compare medications over time and observe trends without storing thousands of individual adverse-event records.

A Note About Large JSON Payloads

One interesting challenge when integrating with public APIs is message size. Initially, I passed the complete JSON response between production components. While this works for small payloads, larger responses can exceed IRIS string limits and I got the <MAXSTRING> error. The solution used in this project is to store the API response as a JSON file and send only its location through the production.

This approach has several advantages:

avoids large interoperability messages
preserves the original API response
makes troubleshooting easier
keeps the production lightweight

It's a useful design pattern whenever you're processing large REST responses or documents.

Summary

In this article, we've built a complete healthcare interoperability production in pure Python using PyProd.

Compared to the previous Electric Utility PyProd sample, this project demonstrates a more realistic integration scenario by communicating with an external REST service instead of processing local files.

Along the way, we've seen how to:

integrate with the public openFDA API
rotate automatically between multiple medications
process large JSON payloads efficiently
calculate batch-level healthcare analytics
archive source payloads
create SQL tables automatically
build an entire InterSystems IRIS production using only Python

Although this example focuses on the openFDA API, the same architecture can easily be adapted to FHIR servers, public health services, hospital APIs, or any REST-based healthcare integration.

I hope this project serves as a useful starting point for building more advanced Python interoperability solutions with PyProd.

45-Second Production: Testing ChatGPT’s Limits with InterSystems IRIS and PyProd

InterSystems Developer — Tue, 28 Jul 2026 19:12:16 +0000

It all started on a train ride to visit my parents, while I was chatting with a neighbor in my compartment. As it usually goes, the talk turned to technology, and she threw out a highly specific question: *Could ChatGPT be used to analyze the human genome?* I was highly skeptical that it could pull off something that complex. But the question lingered, burrowing into my mind. By the time I walked through my front door, my skepticism had transformed into a challenge. I didn't have a genome sequencing dataset on hand, but I did want to see if standard ChatGPT could build a functional Interoperability Production from scratch using the PyProd package. Besides, that would give me the chance to participate in the 1st round of the Community Bounty Program "Idea to Application" implementing the third idea.

I decided to test it with a multi-step prompt:

Using info from the following articles and github repository, write code for a complete InterSystems Production in Python using PyProd package:

step 1: come up with the domain for this production

step 2: create 4 csv files with 30 records in each in the step 1 domain

step 3: write sql create table statement with the structure from csv file

step 4: write inbound adapter in Python using PyProd package that reads the file

step 5: write a business process in Python that analyzes the structure of the step 2 file and makes 1 calculation that makes sense in the step 1 domain

step 6: write business operation in Python to save all the data read in 4 step and the result of calculation from 5 step to the table created in 3 step

Here are the articles and github repositories you should use:

https://community.intersystems.com/post/pyprod-pure-python-iris-interoperability

https://community.intersystems.com/post/pyprod-creating-iris-interoperability-productions-programmatically-python

https://community.intersystems.com/post/csvgen-pyprod https://github.com/intersystems/pyprod

https://github.com/gabriel-ing/csvgen-pyprod

I fed it all to ChatGPT and hit send. Then, I waited. For exactly 45 seconds.

The Delivery and the "Gotchas"

As a result, I got a smart_grid_pyprod.zip containing the ready-to-use code. Naturally, I was dying to know whether it actually worked or was just a convincing hallucination. Playing the part of a complete novice, I asked it how to set everything up. ChatGPT promptly walked me through all necessary steps.

1. Enabling interoperability in the `USER` namespace via the IRIS Terminal:

zn "%SYS"
do ##class(%EnsembleMgr).EnableNamespace("USER")

2. Configuring the environment variables for Windows 11 and installing the package:

set IRISINSTALLDIR=C:\InterSystems\IRIS
set IRISUSERNAME=SuperUser
set IRISPASSWORD=SYS
set IRISNAMESPACE=USER
set PATH=%IRISINSTALLDIR%\mgr\python;%PATH%
python -m pip install intersystems_pyprod --target %IRISINSTALLDIR%\mgr\python --upgrade

3. Compile the generated code using intersystems_pyprod smart_grid.py

4. Open the Management Portal, and start the production.

Did it work right out of the box? Well, no. Mostly, the problems were about commas where they shouldn’t be and a couple of wrongly written async requests, among other things. It took me about half a day to iron out the creases (granted, I was watching Landman in parallel while waiting for Docker to build, turned out to be quite apropos - pumping oil and electricity 😉). But, thanks to some basic Python knowledge and a crucial reference example from @gabriel.Ing, I got it running.

Anatomy of an AI-Generated Production

Once the code was fixed, the production (mostly) written by ChatGPT functioned beautifully. It consists of three components:

The business serviceSmartMeterFileService reads the input file
The business processSmartMeterAnalysisProcess computes per-file total kWh, average kWh, peak meter id, and peak kWh
The business operationSmartMeterDBOperation persists every CSV row with those calculation results

![ ](https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/jmn3lraxygfa1sz48m84.png)

Looking at the Visual Trace in the Management Portal, you can see messages flowing seamlessly from the service to the process and finally to the operation:

And when queried in SQL Explorer

SELECT * 
  FROM EnergyOps.SmartMeterReadings

the data was there, properly calculated, and perfectly structured:

The Verdict: Almost a Success

I would call this experiment an almost success. Almost, because it required me to know at least something about how it works, so the complete novice would be stumped (or would need to ask a lot of follow-up questions).

However, if you have a bit of foundational knowledge, a willingness to troubleshoot, and good community examples to lean on, you can make it work. It proves that while AI might not be ready to architect complex, enterprise-grade genome sequencing pipelines entirely on its own just yet, it is an incredible tool for taking an example and expanding on it to get a prototype off the ground.

Introducing the InterSystems IRIS Document Store for Haystack

InterSystems Developer — Sun, 26 Jul 2026 16:34:15 +0000

Artificial Intelligence applications are increasingly built around Retrieval-Augmented Generation (RAG), semantic search, and AI agents. As these applications move into production, choosing the right persistence layer becomes just as important as selecting the LLM.

Today, I'm excited to announce the InterSystems IRIS Document Store for Haystack, a new open-source integration that enables developers to use InterSystems IRIS as a native Document Store within the Haystack AI framework.

Why Haystack?

Haystack has become one of the leading open-source frameworks for building production-ready AI applications. Its modular pipeline architecture makes it easy to create solutions for:

Retrieval-Augmented Generation (RAG)
Enterprise Search
Question Answering
AI Agents
Semantic Search
Knowledge Assistants

Introducing the Integration

The InterSystems IRIS Document Store implements Haystack's Document Store interface, allowing it to integrate naturally into existing Haystack pipelines.

Whether you're building a small proof of concept or a production RAG system, switching to IRIS as your persistence layer requires minimal changes to your application.

Installation

The package is available on PyPI.

pip install intersystems-iris-haystack

Resources

Official Haystack Integration

https://haystack.deepset.ai/integrations/intersystems-iris-document-store

GitHub Repository

https://github.com/s-c-ai/iris-haystack

PyPI Package

https://pypi.org/project/intersystems-iris-haystack/

Example Architecture

                 Haystack Pipeline

Converter → Splitter → Embedder

            │
            ▼

  InterSystems IRIS Document Store

  • Documents
  • Metadata
  • Vector Search
  • SQL
  • Objects

            │
            ▼

  Retriever → LLM → Answer</code></pre>

Long Running SQL Queries: a sample exploration

InterSystems Developer — Fri, 24 Jul 2026 15:59:40 +0000

Here at InterSystems, we often deal with massive datasets of structured data. It’s not uncommon to see customers with tables spanning >100 fields and >1 billion rows, each table totaling hundred of GB of data. Now imagine joining two or three of these tables together, with a schema that wasn’t optimized for this specific use case. Just for fun, let’s say you have 10 years worth of EMR data from 20 different hospitals across your state, and you’ve been tasked with finding….
every clinician within your network
      who has administered a specific drug
         between the years of 2017-2019
            to patients who reside outside the state
                and have one of the following conditions [diabetes, hypertension, asthma]
                    where the cost was covered by Medicaid

I’ve seen our technology handle these sort of cases just fine, but the query may still take a while to run. Can it be faster though? Let me walk you through a sample investigation.

///////////////////////////////////////////////////////////////////////////////////////////////

The Need:
Find all patients who have had an outpatient encounter at a facility located in one of these counties in the year 2022 or 2023

The Query:
SELECT DISTINCT enc.Patient->PatientNumber
FROM EMR.Encounter as enc
INNER JOIN State_Facility.Address as fa on enc.Facility = fa.FacilityCode
INNER JOIN State_Geography.Cities as city ON city.Zip = fa.ZipCode
WHERE enc.EncounterTime BETWEEN '2022-01-01' AND '2023-12-31'
AND enc.EncounterType IN ('OP','Outpatient','O')
AND city.County IN ('Los Angeles County', 'Orange County', 'Riverside County', 'San Bernardino County', 'Ventura County')

The Performance:
The query was taking >24 hours to complete

INVESTIGATION STEPS:

1) Review the tables that you’re querying. What relationships or foreign keys exist between them? What indices already exist? Is your SQL query making good use of the ones that already exist? Do the indices have Status = Selectable?

We checked each field that was part of a WHERE, AND, or INNER JOIN. Most of them did have indices, including some bitmap indices. [NOTE: Further to the right of the screenshot page, the Status column shows that EncounterTypeIndex is Selectable]

2) Review the Query Plan. Does it make sense? Does it make use of the indices and relationships you expected it would? If not, does it seem more or less efficient?

Yes, the Query Plan showed effective use of the indices on EncounterType and StartTime. [NOTE: This screenshot is for a simplified version of the query that does not consider the zip code of the encounter facility]

3) Ensure the table statistics up to date by running Tune Tables

4) Check whether the actual Query Plan at runtime matches the one you were shown. The "Show Plan" Query Plan does not utilize the Runtime Plan Choice (RTPC) optimization when it generates a Query Plan, but the RTPC is utilized when the query is actually run. That is why the Show Plan Query Plan and the runtime Query Plan can be different. The RTPC algorithm usually finds an optimal choice, but it can sometimes make a poor choice. If we find that the RTPC algorithm is making the wrong choice, it is possible to suppress the RTPC at runtime by using the %NORUNTIME keyword.

Once the query was running, we looked at the Processes page and found the process that was running the query. We found the cached query that it was running (the Routine). We went to that cached query and looked at its Query Plan. We found that it was using a Query Plan that was very different from the one we’d seem before, and it looked much less efficient.

RECOMMENDATIONS:

We recommended that the customer take the following actions:
1) Use the %NORUNTIME keyword when executing the query, forcing it to use the more efficient Query Plan
2) Build a new bitmap index called EncounterDate based on the EncounterTime field. Date-based indices can be faster than DateTime-based indices, and bitmap indices are often significantly faster than normal indices

Once they implemented these two recommendations, their query was now completing in ~6 hours, a 75% improvement.

FURTHER READING:

Check out @benjamin.Spead's excellent collection of resources, which includes links to online documentation, InterSystems online learning courses, presentation slideshows, and Developer Community articles.
https://community.intersystems.com/post/sql-performance-resources

Monitoring InterSystems IRIS with Prometheus and Grafana

InterSystems Developer — Wed, 22 Jul 2026 17:17:48 +0000

Monitoring your IRIS deployment is crucial. With the deprecation of System Alert and Monitoring (SAM), a modern, scalable solution is necessary for real-time insights, early issue detection, and operational efficiency. This guide covers setting up Prometheus and Grafana in Kubernetes to monitor InterSystems IRIS effectively.

This guide assumes you already have an IRIS cluster deployed using the InterSystems Kubernetes Operator (IKO), which simplifies deployment, integration and mangement.

Why Prometheus and Grafana?

Prometheus and Grafana are widely adopted tools for cloud-native monitoring and visualization. Here’s why they are a fit:

Scalability: Prometheus handles large-scale data ingestion efficiently.
Alerting: Customizable alerts via Prometheus Alertmanager.
Visualization: Grafana offers rich, customizable dashboards for Kubernetes metrics.
Ease of Integration: Seamlessly integrates with Kubernetes workloads.

Prerequisites

Before starting, ensure you have the following:

Basic knowledge of Kubernetes and Linux
kubectl and helm installed.
Familiarity with Prometheus concepts (refer to the Prometheus documantion for more information).
A deployed IRIS instance using the InterSystems Kubernetes Operator (IKO), refer to another article here.

Step 1: Enable Metrics in InterSystems IRIS

InterSystems IRIS exposes metrics via /api/monitor/ in the Prometheus format. Ensure this endpoint is enabled:

Open the Management Portal.
Go to System Administration > Security > Applications > Web Applications.
Ensure /api/monitor/ is enabled and accessible by Prometheus. You can check its status by navigating to the Management Portal, going to System Administration > Security > Applications > Web Applications, and verifying that the endpoint is listed and enabled.

Verify its availability by accessing:

http://<IRIS_HOST>:<PORT>/api/monitor/metrics

Step 2: Deploy Prometheus Using Helm

Deploying Prometheus using Helm provides an easy-to-manage monitoring setup. We will use the kube-prometheus-stack chart that includes Prometheus, Alertmanager, and Grafana.

Prepare the configuration: Create a values.yaml file with the following settings:

prometheus:
  prometheusSpec:
    additionalScrapeConfigs:
      - job_name: 'intersystems_iris_metrics'
        metrics_path: '/api/monitor/metrics'
        static_configs:
          - targets:
              - 'iris-app-compute-0.iris-svc.commerce.svc.cluster.local:80' # Replace with your IRIS service

      # To scrape custom metrics from the REST API created in IRIS
      - job_name: 'custom_iris_metrics'
        metrics_path: '/web/metrics'
        static_configs:
          - targets:
              - 'commerce-app-webgateway-0.iris-svc.commerce.svc.cluster.local:80'
        basic_auth:
          username: '_SYSTEM'
          password: 'SYS'

Explanation:
- iris-app-compute-0.iris-svc.commerce.svc.cluster.local:80: The format of the target should follow this convention: <pod-name>-iris-svc.<namespace>.svc.cluster.local:80. Replace <pod-name> with your IRIS pod, specify whether you want to scrape compute or data pods, and adjust the namespace as needed.
- basic_auth** section**: If authentication is required to access the IRIS metrics endpoint, provide the necessary credentials.

Add the Helm repository:

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

Install Prometheus using Helm:

helm install monitoring prometheus-community/kube-prometheus-stack -n monitoring --create-namespace -f values.yaml

Verify the deployment:
```
kubectl get pods -n monitoring
```

Step 3: Custom Metrics with REST API

You can create a custom metrics CSP page that serves your application metrics. In this guide, I provide an example of a simple CSP page that extracts system metrics from IRIS itself, but you can totally build your own CSP page with your own custom metrics—just make sure they are in the Prometheus format.

CustomMetrics.REST

Class CustomMetrics.REST Extends %CSP.REST
{ Parameter HandleCorsRequest = 1; ClassMethod Metrics() As %Status
{
    Try {
        Do %response.SetHeader("Content-Type", "text/plain; version=0.0.4; charset=utf-8")
        New $Namespace Set $Namespace = "%SYS"
        Set ref = ##class(SYS.Stats.Dashboard).Sample()
        Write "# HELP iris_license_high Peak number of licenses used", $CHAR(10)
        Write "# TYPE iris_license_high gauge", $CHAR(10)
        Write "iris_license_high ", ref.LicenseHigh, $CHAR(10)
        Write "# HELP iris_active_processes Number of active processes", $CHAR(10)
        Write "# TYPE iris_active_processes gauge", $CHAR(10)
        Write "iris_active_processes ", ref.Processes, $CHAR(10)
        Write "# HELP iris_application_errors Number of application errors", $CHAR(10)
        Write "# TYPE iris_application_errors counter", $CHAR(10)
        Write "iris_application_errors ", ref.ApplicationErrors, $CHAR(10)
        Return $$$OK
    } Catch ex {
        Do %response.SetHeader("Content-Type", "text/plain")
        Write "Internal Server Error", $CHAR(10)
        Do $System.Status.DisplayError(ex.AsStatus())
        Return $$$ERROR($$$GeneralError, "Internal Server Error")
    }
} 
XData UrlMap
{
<Routes>
    <Route Url="/metrics" Method="GET" Call="Metrics"/>
</Routes>
} 
}

Deploy this as a REST service under a new web application called metrics in IRIS, and add its path to Prometheus for scraping.

Step 4: Verify Prometheus Setup

Open the Prometheus UI (http://<PROMETHEUS_HOST>:9090).
Go to Status > Targets and confirm IRIS metrics are being scraped.

Step 5: Access Grafana

With Prometheus scraping IRIS metrics, the next step is to visualize the data using Grafana.

1. Retrieve the Grafana service details:

kubectl get svc -n monitoring

If you’re using an ingress controller, you can access Grafana using the configured hostname (e.g., http://grafana.example.com). Otherwise, you can use the following options:

Port Forwarding: Use kubectl port-forward to access Grafana locally:
```
kubectl port-forward svc/monitoring-grafana -n monitoring 3000:80
```
Then, access Grafana at http://localhost:3000.
NodePort or ClusterIP: Refer to the NodePort or ClusterIP service details from the command output to connect directly.

Step 6: Log In to Grafana

Use the default credentials to log in:

Username: admin
Password: prom-operator (or the password set during installation).

Step 7: Import a Custom Dashboard

I’ve created a custom dashboard specifically tailored for InterSystems IRIS metrics, which you can use as a starting point for your monitoring needs. The JSON file for this dashboard is hosted on GitHub for easy access and import: Download the Custom Dashboard JSON

To import the dashboard:

Navigate to Dashboards > Import in Grafana.
Paste the URL of the JSON file into the Import via panel JSON field or upload the file directly.
Assign the dashboard to a folder and Prometheus data source when prompted.

Once imported, you can edit the panels to include additional metrics, customize the visualizations, or refine the layout for better insights into your IRIS environment.

Conclusion

By following this guide, we've successfully set up Prometheus to scrape InterSystems IRIS metrics and visualize them using Grafana. Additionally, you can explore other monitoring tools such as Loki to also monitor logs efficiently and configure alerts using Alertmanager or external services like PagerDuty and Slack. If you have any questions or feedback, feel free to reach out!

pyprod: Pure Python IRIS Interoperability

InterSystems Developer — Mon, 20 Jul 2026 15:21:47 +0000

Intersystems IRIS Productions provide a powerful framework for connecting disparate systems across various protocols and message formats in a reliable, observable, and scalable manner. intersystems_pyprod, short for InterSystems Python Productions, is a Python library that enables developers to build these interoperability components entirely in Python. Designed for flexibility, it supports a hybrid approach: you can seamlessly mix new Python-based components with existing ObjectScript-based ones, leveraging your established IRIS infrastructure. Once defined, these Python components are managed just like any other; they can be added, configured, and connected using the IRIS Production Configuration page.

A Quick Primer on InterSystems IRIS Productions

![ ](https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/uxrqudqxu71qyqd568s2.png)

Key Elements of a Production

Image from Learning Services training material

An IRIS Production generally receives data from external interfaces, processes it through coordinated steps, and routes it to its destination. As messages move through the system, they are automatically persisted, making the entire flow fully traceable through IRIS’s visual trace and logging tools. The architecture relies on certain key elements:

Business Hosts: These are the core building blocks—Services, Processes, and Operations—that pass persistable messages between one another.
Adapters: Inbound and outbound adapters manage the interaction with the external world, handling the specific protocols needed to receive and send data.
Callbacks: The engine uses specific callback methods to pass messages between hosts, either synchronously or asynchronously. These callbacks follow strict signatures and return a Status object to ensure execution integrity.
Configuration Helpers: Objects such as Properties and Parameters expose settings to the Production Configuration UI, allowing users to easily instantiate, configure, and save the state of these components.

Workflow using pyprod

This is essentially a 3 step process.

Write your production components in a regular Python script. In that script, you import the required base classes from intersystems_pyprod and define your own components by subclassing them, just as you would with any other Python library.
Load them into InterSystems IRIS by running the intersystems_pyprod (same name as the library) command from the terminal and passing it the path to your Python script. This step links the Python classes with IRIS so that they appear as production components and can be configured and wired together using the standard Production Configuration UI.
Create the production using the Production Configuration page and start the Production

NOTE: If you create all your components with all their Properties hardcoded within the python script, you only need to add them to the production and start the Production.

You can connect pyprod to your IRIS instance by doing a one time setup.

Simple Example

In this example, we demonstrate a synchronous message flow where a request originates from a Service, moves through a Process, and is forwarded to an Operation. The resulting response then travels the same path in reverse, passing from the Operation back through the Process to the Service. Additionally, we showcase how to utilize the IRISLog utility to write custom log entries.

Step 1

Create your Production components using pyprod in the file HelloWorld.py

Here are some key parts of the code

Package Naming: We define iris_package_name, which prefixes all classes as they appear on the Production Configuration page (If omitted, the script name is used as the default prefix).
Persistable Messages: We define MyRequest and MyResponse. These are the essential data structures for communication, as only persistable objects can be passed between Services, Processes, and Operations.
The Inbound Adapter: Our adapter passes a string to the Service using the business_host_process_input method.
The Business Service: Implemented with the help of OnProcessInput callback.
- MyService receives data from the adapter and converts it into a MyRequest message
- We use the ADAPTERIRISParameter to link the Inbound Adapter to the Service. Note that this attribute must be named ADAPTER in all caps to align with IRIS conventions.
- We define a targetIRISProperty, which allows users to select the destination component directly via the Configuration UI.
The Business Process: Implemented with the help of OnRequest callback.
The Business Operation: Implemented with the help of OnMessage callback. (You can also define a MessageMap)
Logic & Callbacks: Finally, the hosts implement their core logic within standard callbacks like OnProcessInput and OnRequest, routing messages using the SendRequestSync method.

You can read more about each of these parts on the pyprod API Reference page and also using the Quick Start Guide.

import time

from intersystems_pyprod import (

    InboundAdapter,BusinessService, BusinessProcess, 

    BusinessOperation, OutboundAdapter, JsonSerialize, 

    IRISProperty, IRISParameter, IRISLog, Status)

iris_package_name = "helloworld"

class MyRequest(JsonSerialize):

    content: str

class MyResponse(JsonSerialize):

    content: str

class MyInAdapter(InboundAdapter):

    def OnTask(self):

        time.sleep(0.5)

        self.business_host_process_input("request message")

        return Status.OK()

class MyService(BusinessService):

    ADAPTER = IRISParameter("helloworld.MyInAdapter")

    target = IRISProperty(settings="Target")

    def OnProcessInput(self, input):

        persistent_message = MyRequest(input)

        status, response = self.SendRequestSync(self.target, persistent_message)

        IRISLog.Info(response.content)

        return status

class MyProcess(BusinessProcess):

    target = IRISProperty(settings="Target")

    def on_request(self, input):

        status, response = self.SendRequestSync(self.target,input)

        return status, response

class MyOperation(BusinessOperation):

    ADAPTER = IRISParameter("helloworld.MyOutAdapter")

    def OnMessage(self, input):

        status = self.ADAPTER.custom_method(input)

        response = MyResponse("response message")

        return status, response

class MyOutAdapter(OutboundAdapter):

    def custom_method(self, input):

        IRISLog.Info(input.content)

        return Status.OK()

Step 2

Once your code is ready, load the components to IRIS.

$ intersystems_pyprod /full/path/to/HelloWorld.py

Loading MyRequest to IRIS...
...
Load finished successfully.

Loading MyResponse to IRIS...
...
Load finished successfully.
...
</code></pre><h3>Step 3</h3><p>Add each host to the Production using the Production Configuration page.</p><p>The image below shows <code data-index-in-node="42" data-path-to-node="3">MyService</code> and its <code data-index-in-node="93" data-path-to-node="3">target</code> property being configured through the UI. Follow the same process to add <code data-index-in-node="176" data-path-to-node="3">MyProcess</code> and <code data-index-in-node="190" data-path-to-node="3">MyOperation</code>. Once the setup is complete, simply start the production to see your messages in motion.</p>






Final Thoughts
By combining the flexibility of the Python ecosystem with the industrial-grade reliability of InterSystems IRIS, pyprod offers a modern path for building interoperability solutions. Whether you are developing entirely new "Pure Python" productions or enhancing existing ObjectScript infrastructures with specialized Python libraries, pyprod ensures your components remain fully integrated, observable, and easy to configure. We look forward to seeing what you build!

Quick Links
GitHub repository  
PyPi Package

Support the Project: If you find this library useful, please consider giving us a ⭐ on GitHub and suggesting enhancements. It helps the project grow and makes it easier for other developers in the InterSystems community to discover it!