llms 0.1.0

data/lib/llms/cli/test_prompt_caching.rb

@@ -0,0 +1,275 @@
+require_relative 'base'
+
+module LLMs
+  module CLI
+    class TestPromptCaching < Base
+      protected
+
+      def default_options
+        super.merge({
+          max_completion_tokens: 10,
+          confirmed: false,
+          system_prompt: "You are a book expert. What is the following excerpt from?",
+          cache_prompt: true ##TODO caching is automatic for most models now - remove this option
+        })
+      end
+
+      def add_custom_options(opts)
+        opts.on('-y', '--yes', 'Skip confirmation warning') { @options[:confirmed] = true }
+      end
+
+      def setup
+        # No model name required for this command
+        true
+      end
+
+      def perform_execution
+        unless @options[:confirmed]
+          puts "\e[33mWarning: Running this test can be expensive as it sends a long prompt to the model and makes multiple API calls."
+          puts "Use -y option to skip this warning and proceed.\e[0m"
+          exit 1
+        end
+
+        if @options[:model_name]
+          test_single_model(create_executor)
+        else
+          test_all_models
+        end
+      end
+
+      def test_all_models
+        models = LLMs::Models.list_model_names(full: true)
+        if ARGV[0]
+          models = models.select { |name| name.include?(ARGV[0]) }
+        end
+        models.each do |model_name|
+          test_single_model(create_executor({model_name: model_name}))
+          puts "-" * 80
+        end
+      end
+
+      def test_single_model(executor)
+        begin
+          puts "First call:"
+          response = executor.execute_prompt(prompt_data)
+          puts response
+          puts "Usage: #{executor.last_usage_data.inspect}"
+
+          puts "\nSecond call:"
+          response = executor.execute_prompt(prompt_data)
+          puts "Response: #{response}"
+          usage = executor.last_usage_data
+          puts "Usage: #{usage.inspect}"
+
+          if usage&.fetch(:cache_was_read, false)
+            puts "\e[32mSUCCESS: Prompt caching detected!\e[0m"
+          else
+            puts "\e[31mFAILURE: Prompt caching not detected!\e[0m"
+          end
+
+        rescue StandardError => e
+          puts "#{executor.model_name}: ERROR - #{e.message}"
+          puts e.backtrace if @options[:debug]
+        end
+      end
+
+      def prompt_data
+        PROMPT_DATA
+      end
+    end
+  end
+end
+
+PROMPT_DATA = <<-PROMPT
+"That is very evident."
+"Absurdly commonplace, is it not?"
+"But the boots and the bath?"
+"Equally childish. You are in the habit of doing up your boots in a certain way. I see them on this occasion fastened with an elaborate double bow, which is not your usual method of tying them. You have, therefore, had them off. Who has tied them? A bootmaker—or the boy at the bath. It is unlikely that it is the bootmaker, since your boots are nearly new. Well, what remains? The bath. Absurd, is it not? But, for all that, the Turkish bath has served a purpose."
+"What is that?"
+"You say that you have had it because you need a change. Let me suggest that you take one. How would Lausanne do, my dear Watson—first-class tickets and all expenses paid on a princely scale?"
+"Splendid! But why?"
+Holmes leaned back in his armchair and took his notebook from his pocket.
+"One of the most dangerous classes in the world," said he, "is the drifting and friendless woman. She is the most harmless and often the most useful of mortals, but she is the inevitable inciter of crime in others. She is helpless. She is migratory. She has sufficient means to take her from country to country and from hotel to hotel. She is lost, as often as not, in a maze of obscure pensions and boardinghouses. She is a stray chicken in a world of foxes. When she is gobbled up she is hardly missed. I much fear that some evil has come to the Lady Frances Carfax."
+I was relieved at this sudden descent from the general to the particular. Holmes consulted his notes.
+"Lady Frances," he continued, "is the sole survivor of the direct family of the late Earl of Rufton. The estates went, as you may remember, in the male line. She was left with limited means, but with some very remarkable old Spanish jewellery of silver and curiously cut diamonds to which she was fondly attached—too attached, for she refused to leave them with her banker and always carried them about with her. A rather pathetic figure, the Lady Frances, a beautiful woman, still in fresh middle age, and yet, by a strange change, the last derelict of what only twenty years ago was a goodly fleet."
+"What has happened to her, then?"
+"Ah, what has happened to the Lady Frances? Is she alive or dead? There is our problem. She is a lady of precise habits, and for four years it has been her invariable custom to write every second week to Miss Dobney, her old governess, who has long retired and lives in Camberwell. It is this Miss Dobney who has consulted me. Nearly five weeks have passed without a word. The last letter was from the Hôtel National at Lausanne. Lady Frances seems to have left there and given no address. The family are anxious, and as they are exceedingly wealthy no sum will be spared if we can clear the matter up."
+"Is Miss Dobney the only source of information? Surely she had other correspondents?"
+"There is one correspondent who is a sure draw, Watson. That is the bank. Single ladies must live, and their passbooks are compressed diaries. She banks at Silvester's. I have glanced over her account. The last check but one paid her bill at Lausanne, but it was a large one and probably left her with cash in hand. Only one check has been drawn since."
+"To whom, and where?"
+"To Miss Marie Devine. There is nothing to show where the check was drawn. It was cashed at the Crédit Lyonnais at Montpellier less than three weeks ago. The sum was fifty pounds."
+"And who is Miss Marie Devine?"
+"That also I have been able to discover. Miss Marie Devine was the maid of Lady Frances Carfax. Why she should have paid her this check we have not yet determined. I have no doubt, however, that your researches will soon clear the matter up."
+"My researches!"
+"Hence the health-giving expedition to Lausanne. You know that I cannot possibly leave London while old Abrahams is in such mortal terror of his life. Besides, on general principles it is best that I should not leave the country. Scotland Yard feels lonely without me, and it causes an unhealthy excitement among the criminal classes. Go, then, my dear Watson, and if my humble counsel can ever be valued at so extravagant a rate as two pence a word, it waits your disposal night and day at the end of the Continental wire."
+Two days later found me at the Hôtel National at Lausanne, where I received every courtesy at the hands of M. Moser, the well-known manager. Lady Frances, as he informed me, had stayed there for several weeks. She had been much liked by all who met her. Her age was not more than forty. She was still handsome and bore every sign of having in her youth been a very lovely woman. M. Moser knew nothing of any valuable jewellery, but it had been remarked by the servants that the heavy trunk in the lady's bedroom was always scrupulously locked. Marie Devine, the maid, was as popular as her mistress. She was actually engaged to one of the head waiters in the hotel, and there was no difficulty in getting her address. It was 11, Rue de Trajan, Montpellier. All this I jotted down and felt that Holmes himself could not have been more adroit in collecting his facts.
+Only one corner still remained in the shadow. No light which I possessed could clear up the cause for the lady's sudden departure. She was very happy at Lausanne. There was every reason to believe that she intended to remain for the season in her luxurious rooms overlooking the lake. And yet she had left at a single day's notice, which involved her in the useless payment of a week's rent. Only Jules Vibart, the lover of the maid, had any suggestion to offer. He connected the sudden departure with the visit to the hotel a day or two before of a tall, dark, bearded man. "Un sauvage—un veritable sauvage!" cried Jules Vibart. The man had rooms somewhere in the town. He had been seen talking earnestly to Madame on the promenade by the lake. Then he had called. She had refused to see him. He was English, but of his name there was no record. Madame had left the place immediately afterwards. Jules Vibart, and, what was of more importance, Jules Vibart's sweetheart, thought that this call and the departure were cause and effect. Only one thing Jules would not discuss. That was the reason why Marie had left her mistress. Of that he could or would say nothing. If I wished to know, I must go to Montpellier and ask her.
+So ended the first chapter of my inquiry. The second was devoted to the place which Lady Frances Carfax had sought when she left Lausanne. Concerning this there had been some secrecy, which confirmed the idea that she had gone with the intention of throwing someone off her track. Otherwise why should not her luggage have been openly labelled for Baden? Both she and it reached the Rhenish spa by some circuitous route. This much I gathered from the manager of Cook's local office. So to Baden I went, after dispatching to Holmes an account of all my proceedings and receiving in reply a telegram of half-humorous commendation.
+At Baden the track was not difficult to follow. Lady Frances had stayed at the Englischer Hof for a fortnight. While there she had made the acquaintance of a Dr. Shlessinger and his wife, a missionary from South America. Like most lonely ladies, Lady Frances found her comfort and occupation in religion. Dr. Shlessinger's remarkable personality, his whole hearted devotion, and the fact that he was recovering from a disease contracted in the exercise of his apostolic duties affected her deeply. She had helped Mrs. Shlessinger in the nursing of the convalescent saint. He spent his day, as the manager described it to me, upon a lounge-chair on the veranda, with an attendant lady upon either side of him. He was preparing a map of the Holy Land, with special reference to the kingdom of the Midianites, upon which he was writing a monograph. Finally, having improved much in health, he and his wife had returned to London, and Lady Frances had started thither in their company. This was just three weeks before, and the manager had heard nothing since. As to the maid, Marie, she had gone off some days beforehand in floods of tears, after informing the other maids that she was leaving service forever. Dr. Shlessinger had paid the bill of the whole party before his departure.
+"By the way," said the landlord in conclusion, "you are not the only friend of Lady Frances Carfax who is inquiring after her just now. Only a week or so ago we had a man here upon the same errand."
+"Did he give a name?" I asked.
+"None; but he was an Englishman, though of an unusual type."
+"A savage?" said I, linking my facts after the fashion of my illustrious friend.
+"Exactly. That describes him very well. He is a bulky, bearded, sunburned fellow, who looks as if he would be more at home in a farmers' inn than in a fashionable hotel. A hard, fierce man, I should think, and one whom I should be sorry to offend."
+Already the mystery began to define itself, as figures grow clearer with the lifting of a fog. Here was this good and pious lady pursued from place to place by a sinister and unrelenting figure. She feared him, or she would not have fled from Lausanne. He had still followed. Sooner or later he would overtake her. Had he already overtaken her? Was that the secret of her continued silence? Could the good people who were her companions not screen her from his violence or his blackmail? What horrible purpose, what deep design, lay behind this long pursuit? There was the problem which I had to solve.
+To Holmes I wrote showing how rapidly and surely I had got down to the roots of the matter. In reply I had a telegram asking for a description of Dr. Shlessinger's left ear. Holmes's ideas of humour are strange and occasionally offensive, so I took no notice of his ill-timed jest—indeed, I had already reached Montpellier in my pursuit of the maid, Marie, before his message came.
+I had no difficulty in finding the ex-servant and in learning all that she could tell me. She was a devoted creature, who had only left her mistress because she was sure that she was in good hands, and because her own approaching marriage made a separation inevitable in any case. Her mistress had, as she confessed with distress, shown some irritability of temper towards her during their stay in Baden, and had even questioned her once as if she had suspicions of her honesty, and this had made the parting easier than it would otherwise have been. Lady Frances had given her fifty pounds as a wedding-present. Like me, Marie viewed with deep distrust the stranger who had driven her mistress from Lausanne. With her own eyes she had seen him seize the lady's wrist with great violence on the public promenade by the lake. He was a fierce and terrible man. She believed that it was out of dread of him that Lady Frances had accepted the escort of the Shlessingers to London. She had never spoken to Marie about it, but many little signs had convinced the maid that her mistress lived in a state of continual nervous apprehension. So far she had got in her narrative, when suddenly she sprang from her chair and her face was convulsed with surprise and fear. "See!" she cried. "The miscreant follows still! There is the very man of whom I speak."
+Through the open sitting-room window I saw a huge, swarthy man with a bristling black beard walking slowly down the centre of the street and staring eagerly at the numbers of the houses. It was clear that, like myself, he was on the track of the maid. Acting upon the impulse of the moment, I rushed out and accosted him.
+"You are an Englishman," I said.
+"What if I am?" he asked with a most villainous scowl.
+"May I ask what your name is?"
+"No, you may not," said he with decision.
+The situation was awkward, but the most direct way is often the best.
+"Where is the Lady Frances Carfax?" I asked.
+He stared at me with amazement.
+"What have you done with her? Why have you pursued her? I insist upon an answer!" said I.
+The fellow gave a bellow of anger and sprang upon me like a tiger. I have held my own in many a struggle, but the man had a grip of iron and the fury of a fiend. His hand was on my throat and my senses were nearly gone before an unshaven French ouvrier in a blue blouse darted out from a cabaret opposite, with a cudgel in his hand, and struck my assailant a sharp crack over the forearm, which made him leave go his hold. He stood for an instant fuming with rage and uncertain whether he should not renew his attack. Then, with a snarl of anger, he left me and entered the cottage from which I had just come. I turned to thank my preserver, who stood beside me in the roadway.
+"Well, Watson," said he, "a very pretty hash you have made of it! I rather think you had better come back with me to London by the night express."
+An hour afterwards, Sherlock Holmes, in his usual garb and style, was seated in my private room at the hotel. His explanation of his sudden and opportune appearance was simplicity itself, for, finding that he could get away from London, he determined to head me off at the next obvious point of my travels. In the disguise of a workingman he had sat in the cabaret waiting for my appearance.
+"And a singularly consistent investigation you have made, my dear Watson," said he. "I cannot at the moment recall any possible blunder which you have omitted. The total effect of your proceeding has been to give the alarm everywhere and yet to discover nothing."
+"Perhaps you would have done no better," I answered bitterly.
+
+
+"That is very evident."
+"Absurdly commonplace, is it not?"
+"But the boots and the bath?"
+"Equally childish. You are in the habit of doing up your boots in a certain way. I see them on this occasion fastened with an elaborate double bow, which is not your usual method of tying them. You have, therefore, had them off. Who has tied them? A bootmaker—or the boy at the bath. It is unlikely that it is the bootmaker, since your boots are nearly new. Well, what remains? The bath. Absurd, is it not? But, for all that, the Turkish bath has served a purpose."
+"What is that?"
+"You say that you have had it because you need a change. Let me suggest that you take one. How would Lausanne do, my dear Watson—first-class tickets and all expenses paid on a princely scale?"
+"Splendid! But why?"
+Holmes leaned back in his armchair and took his notebook from his pocket.
+"One of the most dangerous classes in the world," said he, "is the drifting and friendless woman. She is the most harmless and often the most useful of mortals, but she is the inevitable inciter of crime in others. She is helpless. She is migratory. She has sufficient means to take her from country to country and from hotel to hotel. She is lost, as often as not, in a maze of obscure pensions and boardinghouses. She is a stray chicken in a world of foxes. When she is gobbled up she is hardly missed. I much fear that some evil has come to the Lady Frances Carfax."
+I was relieved at this sudden descent from the general to the particular. Holmes consulted his notes.
+"Lady Frances," he continued, "is the sole survivor of the direct family of the late Earl of Rufton. The estates went, as you may remember, in the male line. She was left with limited means, but with some very remarkable old Spanish jewellery of silver and curiously cut diamonds to which she was fondly attached—too attached, for she refused to leave them with her banker and always carried them about with her. A rather pathetic figure, the Lady Frances, a beautiful woman, still in fresh middle age, and yet, by a strange change, the last derelict of what only twenty years ago was a goodly fleet."
+"What has happened to her, then?"
+"Ah, what has happened to the Lady Frances? Is she alive or dead? There is our problem. She is a lady of precise habits, and for four years it has been her invariable custom to write every second week to Miss Dobney, her old governess, who has long retired and lives in Camberwell. It is this Miss Dobney who has consulted me. Nearly five weeks have passed without a word. The last letter was from the Hôtel National at Lausanne. Lady Frances seems to have left there and given no address. The family are anxious, and as they are exceedingly wealthy no sum will be spared if we can clear the matter up."
+"Is Miss Dobney the only source of information? Surely she had other correspondents?"
+"There is one correspondent who is a sure draw, Watson. That is the bank. Single ladies must live, and their passbooks are compressed diaries. She banks at Silvester's. I have glanced over her account. The last check but one paid her bill at Lausanne, but it was a large one and probably left her with cash in hand. Only one check has been drawn since."
+"To whom, and where?"
+"To Miss Marie Devine. There is nothing to show where the check was drawn. It was cashed at the Crédit Lyonnais at Montpellier less than three weeks ago. The sum was fifty pounds."
+"And who is Miss Marie Devine?"
+"That also I have been able to discover. Miss Marie Devine was the maid of Lady Frances Carfax. Why she should have paid her this check we have not yet determined. I have no doubt, however, that your researches will soon clear the matter up."
+"My researches!"
+"Hence the health-giving expedition to Lausanne. You know that I cannot possibly leave London while old Abrahams is in such mortal terror of his life. Besides, on general principles it is best that I should not leave the country. Scotland Yard feels lonely without me, and it causes an unhealthy excitement among the criminal classes. Go, then, my dear Watson, and if my humble counsel can ever be valued at so extravagant a rate as two pence a word, it waits your disposal night and day at the end of the Continental wire."
+Two days later found me at the Hôtel National at Lausanne, where I received every courtesy at the hands of M. Moser, the well-known manager. Lady Frances, as he informed me, had stayed there for several weeks. She had been much liked by all who met her. Her age was not more than forty. She was still handsome and bore every sign of having in her youth been a very lovely woman. M. Moser knew nothing of any valuable jewellery, but it had been remarked by the servants that the heavy trunk in the lady's bedroom was always scrupulously locked. Marie Devine, the maid, was as popular as her mistress. She was actually engaged to one of the head waiters in the hotel, and there was no difficulty in getting her address. It was 11, Rue de Trajan, Montpellier. All this I jotted down and felt that Holmes himself could not have been more adroit in collecting his facts.
+Only one corner still remained in the shadow. No light which I possessed could clear up the cause for the lady's sudden departure. She was very happy at Lausanne. There was every reason to believe that she intended to remain for the season in her luxurious rooms overlooking the lake. And yet she had left at a single day's notice, which involved her in the useless payment of a week's rent. Only Jules Vibart, the lover of the maid, had any suggestion to offer. He connected the sudden departure with the visit to the hotel a day or two before of a tall, dark, bearded man. "Un sauvage—un veritable sauvage!" cried Jules Vibart. The man had rooms somewhere in the town. He had been seen talking earnestly to Madame on the promenade by the lake. Then he had called. She had refused to see him. He was English, but of his name there was no record. Madame had left the place immediately afterwards. Jules Vibart, and, what was of more importance, Jules Vibart's sweetheart, thought that this call and the departure were cause and effect. Only one thing Jules would not discuss. That was the reason why Marie had left her mistress. Of that he could or would say nothing. If I wished to know, I must go to Montpellier and ask her.
+So ended the first chapter of my inquiry. The second was devoted to the place which Lady Frances Carfax had sought when she left Lausanne. Concerning this there had been some secrecy, which confirmed the idea that she had gone with the intention of throwing someone off her track. Otherwise why should not her luggage have been openly labelled for Baden? Both she and it reached the Rhenish spa by some circuitous route. This much I gathered from the manager of Cook's local office. So to Baden I went, after dispatching to Holmes an account of all my proceedings and receiving in reply a telegram of half-humorous commendation.
+At Baden the track was not difficult to follow. Lady Frances had stayed at the Englischer Hof for a fortnight. While there she had made the acquaintance of a Dr. Shlessinger and his wife, a missionary from South America. Like most lonely ladies, Lady Frances found her comfort and occupation in religion. Dr. Shlessinger's remarkable personality, his whole hearted devotion, and the fact that he was recovering from a disease contracted in the exercise of his apostolic duties affected her deeply. She had helped Mrs. Shlessinger in the nursing of the convalescent saint. He spent his day, as the manager described it to me, upon a lounge-chair on the veranda, with an attendant lady upon either side of him. He was preparing a map of the Holy Land, with special reference to the kingdom of the Midianites, upon which he was writing a monograph. Finally, having improved much in health, he and his wife had returned to London, and Lady Frances had started thither in their company. This was just three weeks before, and the manager had heard nothing since. As to the maid, Marie, she had gone off some days beforehand in floods of tears, after informing the other maids that she was leaving service forever. Dr. Shlessinger had paid the bill of the whole party before his departure.
+"By the way," said the landlord in conclusion, "you are not the only friend of Lady Frances Carfax who is inquiring after her just now. Only a week or so ago we had a man here upon the same errand."
+"Did he give a name?" I asked.
+"None; but he was an Englishman, though of an unusual type."
+"A savage?" said I, linking my facts after the fashion of my illustrious friend.
+"Exactly. That describes him very well. He is a bulky, bearded, sunburned fellow, who looks as if he would be more at home in a farmers' inn than in a fashionable hotel. A hard, fierce man, I should think, and one whom I should be sorry to offend."
+Already the mystery began to define itself, as figures grow clearer with the lifting of a fog. Here was this good and pious lady pursued from place to place by a sinister and unrelenting figure. She feared him, or she would not have fled from Lausanne. He had still followed. Sooner or later he would overtake her. Had he already overtaken her? Was that the secret of her continued silence? Could the good people who were her companions not screen her from his violence or his blackmail? What horrible purpose, what deep design, lay behind this long pursuit? There was the problem which I had to solve.
+To Holmes I wrote showing how rapidly and surely I had got down to the roots of the matter. In reply I had a telegram asking for a description of Dr. Shlessinger's left ear. Holmes's ideas of humour are strange and occasionally offensive, so I took no notice of his ill-timed jest—indeed, I had already reached Montpellier in my pursuit of the maid, Marie, before his message came.
+I had no difficulty in finding the ex-servant and in learning all that she could tell me. She was a devoted creature, who had only left her mistress because she was sure that she was in good hands, and because her own approaching marriage made a separation inevitable in any case. Her mistress had, as she confessed with distress, shown some irritability of temper towards her during their stay in Baden, and had even questioned her once as if she had suspicions of her honesty, and this had made the parting easier than it would otherwise have been. Lady Frances had given her fifty pounds as a wedding-present. Like me, Marie viewed with deep distrust the stranger who had driven her mistress from Lausanne. With her own eyes she had seen him seize the lady's wrist with great violence on the public promenade by the lake. He was a fierce and terrible man. She believed that it was out of dread of him that Lady Frances had accepted the escort of the Shlessingers to London. She had never spoken to Marie about it, but many little signs had convinced the maid that her mistress lived in a state of continual nervous apprehension. So far she had got in her narrative, when suddenly she sprang from her chair and her face was convulsed with surprise and fear. "See!" she cried. "The miscreant follows still! There is the very man of whom I speak."
+Through the open sitting-room window I saw a huge, swarthy man with a bristling black beard walking slowly down the centre of the street and staring eagerly at the numbers of the houses. It was clear that, like myself, he was on the track of the maid. Acting upon the impulse of the moment, I rushed out and accosted him.
+"You are an Englishman," I said.
+"What if I am?" he asked with a most villainous scowl.
+"May I ask what your name is?"
+"No, you may not," said he with decision.
+The situation was awkward, but the most direct way is often the best.
+"Where is the Lady Frances Carfax?" I asked.
+He stared at me with amazement.
+"What have you done with her? Why have you pursued her? I insist upon an answer!" said I.
+The fellow gave a bellow of anger and sprang upon me like a tiger. I have held my own in many a struggle, but the man had a grip of iron and the fury of a fiend. His hand was on my throat and my senses were nearly gone before an unshaven French ouvrier in a blue blouse darted out from a cabaret opposite, with a cudgel in his hand, and struck my assailant a sharp crack over the forearm, which made him leave go his hold. He stood for an instant fuming with rage and uncertain whether he should not renew his attack. Then, with a snarl of anger, he left me and entered the cottage from which I had just come. I turned to thank my preserver, who stood beside me in the roadway.
+"Well, Watson," said he, "a very pretty hash you have made of it! I rather think you had better come back with me to London by the night express."
+An hour afterwards, Sherlock Holmes, in his usual garb and style, was seated in my private room at the hotel. His explanation of his sudden and opportune appearance was simplicity itself, for, finding that he could get away from London, he determined to head me off at the next obvious point of my travels. In the disguise of a workingman he had sat in the cabaret waiting for my appearance.
+"And a singularly consistent investigation you have made, my dear Watson," said he. "I cannot at the moment recall any possible blunder which you have omitted. The total effect of your proceeding has been to give the alarm everywhere and yet to discover nothing."
+"Perhaps you would have done no better," I answered bitterly.
+"That is very evident."
+"Absurdly commonplace, is it not?"
+"But the boots and the bath?"
+"Equally childish. You are in the habit of doing up your boots in a certain way. I see them on this occasion fastened with an elaborate double bow, which is not your usual method of tying them. You have, therefore, had them off. Who has tied them? A bootmaker—or the boy at the bath. It is unlikely that it is the bootmaker, since your boots are nearly new. Well, what remains? The bath. Absurd, is it not? But, for all that, the Turkish bath has served a purpose."
+"What is that?"
+"You say that you have had it because you need a change. Let me suggest that you take one. How would Lausanne do, my dear Watson—first-class tickets and all expenses paid on a princely scale?"
+"Splendid! But why?"
+Holmes leaned back in his armchair and took his notebook from his pocket.
+"One of the most dangerous classes in the world," said he, "is the drifting and friendless woman. She is the most harmless and often the most useful of mortals, but she is the inevitable inciter of crime in others. She is helpless. She is migratory. She has sufficient means to take her from country to country and from hotel to hotel. She is lost, as often as not, in a maze of obscure pensions and boardinghouses. She is a stray chicken in a world of foxes. When she is gobbled up she is hardly missed. I much fear that some evil has come to the Lady Frances Carfax."
+I was relieved at this sudden descent from the general to the particular. Holmes consulted his notes.
+"Lady Frances," he continued, "is the sole survivor of the direct family of the late Earl of Rufton. The estates went, as you may remember, in the male line. She was left with limited means, but with some very remarkable old Spanish jewellery of silver and curiously cut diamonds to which she was fondly attached—too attached, for she refused to leave them with her banker and always carried them about with her. A rather pathetic figure, the Lady Frances, a beautiful woman, still in fresh middle age, and yet, by a strange change, the last derelict of what only twenty years ago was a goodly fleet."
+"What has happened to her, then?"
+"Ah, what has happened to the Lady Frances? Is she alive or dead? There is our problem. She is a lady of precise habits, and for four years it has been her invariable custom to write every second week to Miss Dobney, her old governess, who has long retired and lives in Camberwell. It is this Miss Dobney who has consulted me. Nearly five weeks have passed without a word. The last letter was from the Hôtel National at Lausanne. Lady Frances seems to have left there and given no address. The family are anxious, and as they are exceedingly wealthy no sum will be spared if we can clear the matter up."
+"Is Miss Dobney the only source of information? Surely she had other correspondents?"
+"There is one correspondent who is a sure draw, Watson. That is the bank. Single ladies must live, and their passbooks are compressed diaries. She banks at Silvester's. I have glanced over her account. The last check but one paid her bill at Lausanne, but it was a large one and probably left her with cash in hand. Only one check has been drawn since."
+"To whom, and where?"
+"To Miss Marie Devine. There is nothing to show where the check was drawn. It was cashed at the Crédit Lyonnais at Montpellier less than three weeks ago. The sum was fifty pounds."
+"And who is Miss Marie Devine?"
+"That also I have been able to discover. Miss Marie Devine was the maid of Lady Frances Carfax. Why she should have paid her this check we have not yet determined. I have no doubt, however, that your researches will soon clear the matter up."
+"My researches!"
+"Hence the health-giving expedition to Lausanne. You know that I cannot possibly leave London while old Abrahams is in such mortal terror of his life. Besides, on general principles it is best that I should not leave the country. Scotland Yard feels lonely without me, and it causes an unhealthy excitement among the criminal classes. Go, then, my dear Watson, and if my humble counsel can ever be valued at so extravagant a rate as two pence a word, it waits your disposal night and day at the end of the Continental wire."
+Two days later found me at the Hôtel National at Lausanne, where I received every courtesy at the hands of M. Moser, the well-known manager. Lady Frances, as he informed me, had stayed there for several weeks. She had been much liked by all who met her. Her age was not more than forty. She was still handsome and bore every sign of having in her youth been a very lovely woman. M. Moser knew nothing of any valuable jewellery, but it had been remarked by the servants that the heavy trunk in the lady's bedroom was always scrupulously locked. Marie Devine, the maid, was as popular as her mistress. She was actually engaged to one of the head waiters in the hotel, and there was no difficulty in getting her address. It was 11, Rue de Trajan, Montpellier. All this I jotted down and felt that Holmes himself could not have been more adroit in collecting his facts.
+Only one corner still remained in the shadow. No light which I possessed could clear up the cause for the lady's sudden departure. She was very happy at Lausanne. There was every reason to believe that she intended to remain for the season in her luxurious rooms overlooking the lake. And yet she had left at a single day's notice, which involved her in the useless payment of a week's rent. Only Jules Vibart, the lover of the maid, had any suggestion to offer. He connected the sudden departure with the visit to the hotel a day or two before of a tall, dark, bearded man. "Un sauvage—un veritable sauvage!" cried Jules Vibart. The man had rooms somewhere in the town. He had been seen talking earnestly to Madame on the promenade by the lake. Then he had called. She had refused to see him. He was English, but of his name there was no record. Madame had left the place immediately afterwards. Jules Vibart, and, what was of more importance, Jules Vibart's sweetheart, thought that this call and the departure were cause and effect. Only one thing Jules would not discuss. That was the reason why Marie had left her mistress. Of that he could or would say nothing. If I wished to know, I must go to Montpellier and ask her.
+So ended the first chapter of my inquiry. The second was devoted to the place which Lady Frances Carfax had sought when she left Lausanne. Concerning this there had been some secrecy, which confirmed the idea that she had gone with the intention of throwing someone off her track. Otherwise why should not her luggage have been openly labelled for Baden? Both she and it reached the Rhenish spa by some circuitous route. This much I gathered from the manager of Cook's local office. So to Baden I went, after dispatching to Holmes an account of all my proceedings and receiving in reply a telegram of half-humorous commendation.
+At Baden the track was not difficult to follow. Lady Frances had stayed at the Englischer Hof for a fortnight. While there she had made the acquaintance of a Dr. Shlessinger and his wife, a missionary from South America. Like most lonely ladies, Lady Frances found her comfort and occupation in religion. Dr. Shlessinger's remarkable personality, his whole hearted devotion, and the fact that he was recovering from a disease contracted in the exercise of his apostolic duties affected her deeply. She had helped Mrs. Shlessinger in the nursing of the convalescent saint. He spent his day, as the manager described it to me, upon a lounge-chair on the veranda, with an attendant lady upon either side of him. He was preparing a map of the Holy Land, with special reference to the kingdom of the Midianites, upon which he was writing a monograph. Finally, having improved much in health, he and his wife had returned to London, and Lady Frances had started thither in their company. This was just three weeks before, and the manager had heard nothing since. As to the maid, Marie, she had gone off some days beforehand in floods of tears, after informing the other maids that she was leaving service forever. Dr. Shlessinger had paid the bill of the whole party before his departure.
+"By the way," said the landlord in conclusion, "you are not the only friend of Lady Frances Carfax who is inquiring after her just now. Only a week or so ago we had a man here upon the same errand."
+"Did he give a name?" I asked.
+"None; but he was an Englishman, though of an unusual type."
+"A savage?" said I, linking my facts after the fashion of my illustrious friend.
+"Exactly. That describes him very well. He is a bulky, bearded, sunburned fellow, who looks as if he would be more at home in a farmers' inn than in a fashionable hotel. A hard, fierce man, I should think, and one whom I should be sorry to offend."
+Already the mystery began to define itself, as figures grow clearer with the lifting of a fog. Here was this good and pious lady pursued from place to place by a sinister and unrelenting figure. She feared him, or she would not have fled from Lausanne. He had still followed. Sooner or later he would overtake her. Had he already overtaken her? Was that the secret of her continued silence? Could the good people who were her companions not screen her from his violence or his blackmail? What horrible purpose, what deep design, lay behind this long pursuit? There was the problem which I had to solve.
+To Holmes I wrote showing how rapidly and surely I had got down to the roots of the matter. In reply I had a telegram asking for a description of Dr. Shlessinger's left ear. Holmes's ideas of humour are strange and occasionally offensive, so I took no notice of his ill-timed jest—indeed, I had already reached Montpellier in my pursuit of the maid, Marie, before his message came.
+I had no difficulty in finding the ex-servant and in learning all that she could tell me. She was a devoted creature, who had only left her mistress because she was sure that she was in good hands, and because her own approaching marriage made a separation inevitable in any case. Her mistress had, as she confessed with distress, shown some irritability of temper towards her during their stay in Baden, and had even questioned her once as if she had suspicions of her honesty, and this had made the parting easier than it would otherwise have been. Lady Frances had given her fifty pounds as a wedding-present. Like me, Marie viewed with deep distrust the stranger who had driven her mistress from Lausanne. With her own eyes she had seen him seize the lady's wrist with great violence on the public promenade by the lake. He was a fierce and terrible man. She believed that it was out of dread of him that Lady Frances had accepted the escort of the Shlessingers to London. She had never spoken to Marie about it, but many little signs had convinced the maid that her mistress lived in a state of continual nervous apprehension. So far she had got in her narrative, when suddenly she sprang from her chair and her face was convulsed with surprise and fear. "See!" she cried. "The miscreant follows still! There is the very man of whom I speak."
+Through the open sitting-room window I saw a huge, swarthy man with a bristling black beard walking slowly down the centre of the street and staring eagerly at the numbers of the houses. It was clear that, like myself, he was on the track of the maid. Acting upon the impulse of the moment, I rushed out and accosted him.
+"You are an Englishman," I said.
+"What if I am?" he asked with a most villainous scowl.
+"May I ask what your name is?"
+"No, you may not," said he with decision.
+The situation was awkward, but the most direct way is often the best.
+"Where is the Lady Frances Carfax?" I asked.
+He stared at me with amazement.
+"What have you done with her? Why have you pursued her? I insist upon an answer!" said I.
+The fellow gave a bellow of anger and sprang upon me like a tiger. I have held my own in many a struggle, but the man had a grip of iron and the fury of a fiend. His hand was on my throat and my senses were nearly gone before an unshaven French ouvrier in a blue blouse darted out from a cabaret opposite, with a cudgel in his hand, and struck my assailant a sharp crack over the forearm, which made him leave go his hold. He stood for an instant fuming with rage and uncertain whether he should not renew his attack. Then, with a snarl of anger, he left me and entered the cottage from which I had just come. I turned to thank my preserver, who stood beside me in the roadway.
+"Well, Watson," said he, "a very pretty hash you have made of it! I rather think you had better come back with me to London by the night express."
+An hour afterwards, Sherlock Holmes, in his usual garb and style, was seated in my private room at the hotel. His explanation of his sudden and opportune appearance was simplicity itself, for, finding that he could get away from London, he determined to head me off at the next obvious point of my travels. In the disguise of a workingman he had sat in the cabaret waiting for my appearance.
+"And a singularly consistent investigation you have made, my dear Watson," said he. "I cannot at the moment recall any possible blunder which you have omitted. The total effect of your proceeding has been to give the alarm everywhere and yet to discover nothing."
+"Perhaps you would have done no better," I answered bitterly.
+"That is very evident."
+"Absurdly commonplace, is it not?"
+"But the boots and the bath?"
+"Equally childish. You are in the habit of doing up your boots in a certain way. I see them on this occasion fastened with an elaborate double bow, which is not your usual method of tying them. You have, therefore, had them off. Who has tied them? A bootmaker—or the boy at the bath. It is unlikely that it is the bootmaker, since your boots are nearly new. Well, what remains? The bath. Absurd, is it not? But, for all that, the Turkish bath has served a purpose."
+"What is that?"
+"You say that you have had it because you need a change. Let me suggest that you take one. How would Lausanne do, my dear Watson—first-class tickets and all expenses paid on a princely scale?"
+"Splendid! But why?"
+Holmes leaned back in his armchair and took his notebook from his pocket.
+"One of the most dangerous classes in the world," said he, "is the drifting and friendless woman. She is the most harmless and often the most useful of mortals, but she is the inevitable inciter of crime in others. She is helpless. She is migratory. She has sufficient means to take her from country to country and from hotel to hotel. She is lost, as often as not, in a maze of obscure pensions and boardinghouses. She is a stray chicken in a world of foxes. When she is gobbled up she is hardly missed. I much fear that some evil has come to the Lady Frances Carfax."
+I was relieved at this sudden descent from the general to the particular. Holmes consulted his notes.
+"Lady Frances," he continued, "is the sole survivor of the direct family of the late Earl of Rufton. The estates went, as you may remember, in the male line. She was left with limited means, but with some very remarkable old Spanish jewellery of silver and curiously cut diamonds to which she was fondly attached—too attached, for she refused to leave them with her banker and always carried them about with her. A rather pathetic figure, the Lady Frances, a beautiful woman, still in fresh middle age, and yet, by a strange change, the last derelict of what only twenty years ago was a goodly fleet."
+"What has happened to her, then?"
+"Ah, what has happened to the Lady Frances? Is she alive or dead? There is our problem. She is a lady of precise habits, and for four years it has been her invariable custom to write every second week to Miss Dobney, her old governess, who has long retired and lives in Camberwell. It is this Miss Dobney who has consulted me. Nearly five weeks have passed without a word. The last letter was from the Hôtel National at Lausanne. Lady Frances seems to have left there and given no address. The family are anxious, and as they are exceedingly wealthy no sum will be spared if we can clear the matter up."
+"Is Miss Dobney the only source of information? Surely she had other correspondents?"
+"There is one correspondent who is a sure draw, Watson. That is the bank. Single ladies must live, and their passbooks are compressed diaries. She banks at Silvester's. I have glanced over her account. The last check but one paid her bill at Lausanne, but it was a large one and probably left her with cash in hand. Only one check has been drawn since."
+"To whom, and where?"
+"To Miss Marie Devine. There is nothing to show where the check was drawn. It was cashed at the Crédit Lyonnais at Montpellier less than three weeks ago. The sum was fifty pounds."
+"And who is Miss Marie Devine?"
+"That also I have been able to discover. Miss Marie Devine was the maid of Lady Frances Carfax. Why she should have paid her this check we have not yet determined. I have no doubt, however, that your researches will soon clear the matter up."
+"My researches!"
+"Hence the health-giving expedition to Lausanne. You know that I cannot possibly leave London while old Abrahams is in such mortal terror of his life. Besides, on general principles it is best that I should not leave the country. Scotland Yard feels lonely without me, and it causes an unhealthy excitement among the criminal classes. Go, then, my dear Watson, and if my humble counsel can ever be valued at so extravagant a rate as two pence a word, it waits your disposal night and day at the end of the Continental wire."
+Two days later found me at the Hôtel National at Lausanne, where I received every courtesy at the hands of M. Moser, the well-known manager. Lady Frances, as he informed me, had stayed there for several weeks. She had been much liked by all who met her. Her age was not more than forty. She was still handsome and bore every sign of having in her youth been a very lovely woman. M. Moser knew nothing of any valuable jewellery, but it had been remarked by the servants that the heavy trunk in the lady's bedroom was always scrupulously locked. Marie Devine, the maid, was as popular as her mistress. She was actually engaged to one of the head waiters in the hotel, and there was no difficulty in getting her address. It was 11, Rue de Trajan, Montpellier. All this I jotted down and felt that Holmes himself could not have been more adroit in collecting his facts.
+Only one corner still remained in the shadow. No light which I possessed could clear up the cause for the lady's sudden departure. She was very happy at Lausanne. There was every reason to believe that she intended to remain for the season in her luxurious rooms overlooking the lake. And yet she had left at a single day's notice, which involved her in the useless payment of a week's rent. Only Jules Vibart, the lover of the maid, had any suggestion to offer. He connected the sudden departure with the visit to the hotel a day or two before of a tall, dark, bearded man. "Un sauvage—un veritable sauvage!" cried Jules Vibart. The man had rooms somewhere in the town. He had been seen talking earnestly to Madame on the promenade by the lake. Then he had called. She had refused to see him. He was English, but of his name there was no record. Madame had left the place immediately afterwards. Jules Vibart, and, what was of more importance, Jules Vibart's sweetheart, thought that this call and the departure were cause and effect. Only one thing Jules would not discuss. That was the reason why Marie had left her mistress. Of that he could or would say nothing. If I wished to know, I must go to Montpellier and ask her.
+So ended the first chapter of my inquiry. The second was devoted to the place which Lady Frances Carfax had sought when she left Lausanne. Concerning this there had been some secrecy, which confirmed the idea that she had gone with the intention of throwing someone off her track. Otherwise why should not her luggage have been openly labelled for Baden? Both she and it reached the Rhenish spa by some circuitous route. This much I gathered from the manager of Cook's local office. So to Baden I went, after dispatching to Holmes an account of all my proceedings and receiving in reply a telegram of half-humorous commendation.
+At Baden the track was not difficult to follow. Lady Frances had stayed at the Englischer Hof for a fortnight. While there she had made the acquaintance of a Dr. Shlessinger and his wife, a missionary from South America. Like most lonely ladies, Lady Frances found her comfort and occupation in religion. Dr. Shlessinger's remarkable personality, his whole hearted devotion, and the fact that he was recovering from a disease contracted in the exercise of his apostolic duties affected her deeply. She had helped Mrs. Shlessinger in the nursing of the convalescent saint. He spent his day, as the manager described it to me, upon a lounge-chair on the veranda, with an attendant lady upon either side of him. He was preparing a map of the Holy Land, with special reference to the kingdom of the Midianites, upon which he was writing a monograph. Finally, having improved much in health, he and his wife had returned to London, and Lady Frances had started thither in their company. This was just three weeks before, and the manager had heard nothing since. As to the maid, Marie, she had gone off some days beforehand in floods of tears, after informing the other maids that she was leaving service forever. Dr. Shlessinger had paid the bill of the whole party before his departure.
+"By the way," said the landlord in conclusion, "you are not the only friend of Lady Frances Carfax who is inquiring after her just now. Only a week or so ago we had a man here upon the same errand."
+"Did he give a name?" I asked.
+"None; but he was an Englishman, though of an unusual type."
+"A savage?" said I, linking my facts after the fashion of my illustrious friend.
+"Exactly. That describes him very well. He is a bulky, bearded, sunburned fellow, who looks as if he would be more at home in a farmers' inn than in a fashionable hotel. A hard, fierce man, I should think, and one whom I should be sorry to offend."
+Already the mystery began to define itself, as figures grow clearer with the lifting of a fog. Here was this good and pious lady pursued from place to place by a sinister and unrelenting figure. She feared him, or she would not have fled from Lausanne. He had still followed. Sooner or later he would overtake her. Had he already overtaken her? Was that the secret of her continued silence? Could the good people who were her companions not screen her from his violence or his blackmail? What horrible purpose, what deep design, lay behind this long pursuit? There was the problem which I had to solve.
+To Holmes I wrote showing how rapidly and surely I had got down to the roots of the matter. In reply I had a telegram asking for a description of Dr. Shlessinger's left ear. Holmes's ideas of humour are strange and occasionally offensive, so I took no notice of his ill-timed jest—indeed, I had already reached Montpellier in my pursuit of the maid, Marie, before his message came.
+I had no difficulty in finding the ex-servant and in learning all that she could tell me. She was a devoted creature, who had only left her mistress because she was sure that she was in good hands, and because her own approaching marriage made a separation inevitable in any case. Her mistress had, as she confessed with distress, shown some irritability of temper towards her during their stay in Baden, and had even questioned her once as if she had suspicions of her honesty, and this had made the parting easier than it would otherwise have been. Lady Frances had given her fifty pounds as a wedding-present. Like me, Marie viewed with deep distrust the stranger who had driven her mistress from Lausanne. With her own eyes she had seen him seize the lady's wrist with great violence on the public promenade by the lake. He was a fierce and terrible man. She believed that it was out of dread of him that Lady Frances had accepted the escort of the Shlessingers to London. She had never spoken to Marie about it, but many little signs had convinced the maid that her mistress lived in a state of continual nervous apprehension. So far she had got in her narrative, when suddenly she sprang from her chair and her face was convulsed with surprise and fear. "See!" she cried. "The miscreant follows still! There is the very man of whom I speak."
+Through the open sitting-room window I saw a huge, swarthy man with a bristling black beard walking slowly down the centre of the street and staring eagerly at the numbers of the houses. It was clear that, like myself, he was on the track of the maid. Acting upon the impulse of the moment, I rushed out and accosted him.
+"You are an Englishman," I said.
+"What if I am?" he asked with a most villainous scowl.
+"May I ask what your name is?"
+"No, you may not," said he with decision.
+The situation was awkward, but the most direct way is often the best.
+"Where is the Lady Frances Carfax?" I asked.
+He stared at me with amazement.
+"What have you done with her? Why have you pursued her? I insist upon an answer!" said I.
+The fellow gave a bellow of anger and sprang upon me like a tiger. I have held my own in many a struggle, but the man had a grip of iron and the fury of a fiend. His hand was on my throat and my senses were nearly gone before an unshaven French ouvrier in a blue blouse darted out from a cabaret opposite, with a cudgel in his hand, and struck my assailant a sharp crack over the forearm, which made him leave go his hold. He stood for an instant fuming with rage and uncertain whether he should not renew his attack. Then, with a snarl of anger, he left me and entered the cottage from which I had just come. I turned to thank my preserver, who stood beside me in the roadway.
+"Well, Watson," said he, "a very pretty hash you have made of it! I rather think you had better come back with me to London by the night express."
+An hour afterwards, Sherlock Holmes, in his usual garb and style, was seated in my private room at the hotel. His explanation of his sudden and opportune appearance was simplicity itself, for, finding that he could get away from London, he determined to head me off at the next obvious point of my travels. In the disguise of a workingman he had sat in the cabaret waiting for my appearance.
+"And a singularly consistent investigation you have made, my dear Watson," said he. "I cannot at the moment recall any possible blunder which you have omitted. The total effect of your proceeding has been to give the alarm everywhere and yet to discover nothing."
+"Perhaps you would have done no better," I answered bitterly.
+
+PROMPT

data/lib/llms/cli/test_tool_use.rb

@@ -0,0 +1,108 @@
+require_relative 'base'
+require_relative '../conversation'
+
+module LLMs
+  module CLI
+    class TestToolUse < Base
+      class CalculatorTool
+        def self.tool_schema
+          {
+            name: 'calculator_tool',
+            description: 'Compute a plain-text arithmetic calculation using the operators + - * / and parens (). E.g. (2 + 2) / (3 - 1)',
+            parameters: {
+              properties: {
+                calculation: {
+                  type: 'string',
+                  description: 'The arithmetic operation to perform'
+                },
+              },
+              type: 'object',
+            }
+          }
+        end
+      end
+
+      protected
+
+      def default_options
+        super.merge({
+          max_completion_tokens: 1000,
+          prompt: "2+2=",
+          system_prompt: "Always reply with a tool use function call"
+        })
+      end
+
+      def add_custom_options(opts)
+        opts.on("--prompt PROMPT", "Test prompt to use") do |prompt|
+          @options[:prompt] = prompt
+        end
+      end
+
+      def setup
+        # No model name required for this command
+        true
+      end
+
+      def perform_execution
+        if @options[:model_name]
+          test_single_model(create_executor)
+        else
+          test_all_models
+        end
+      end
+
+      private
+
+      def test_single_model(executor)
+        begin
+          cm = LLMs::Conversation.new
+          cm.set_system_message(@options[:system_prompt])
+          cm.set_available_tools([CalculatorTool])
+          cm.add_user_message(@options[:prompt])
+
+          if @options[:stream]
+            executor.execute_conversation(cm) do |chunk|
+              print chunk
+            end
+            puts
+          else
+            response_message = executor.execute_conversation(cm)
+            puts response_message&.text
+          end
+
+          # Display tool calls if present
+          if executor.last_received_message&.tool_calls
+            puts 'Tool calls: ' + executor.last_received_message.tool_calls.map { |tc| "#{tc.name}: #{tc.arguments} - #{tc.tool_call_id}" }.join(', ')
+          end
+
+          report_error(executor)
+          report_usage(executor)
+
+        rescue StandardError => e
+          puts "#{executor.model_name}: ERROR - #{e.message}"
+          puts e.backtrace if @options[:debug]
+        end
+      end
+
+      def test_all_models
+        models = get_models_to_test
+
+        models.each do |model_name|
+          test_single_model(create_executor({model_name: model_name}))
+          puts "-" * 80
+        end
+      end
+
+      def get_models_to_test
+        models = LLMs::Models.list_model_names(full: true, require_tools: true)
+
+        # Filter by model name if provided
+        if ARGV[0]
+          models = models.select { |name| name.include?(ARGV[0]) }
+        end
+
+        models
+      end
+    end
+  end
+end

data/lib/llms/cli.rb

@@ -0,0 +1,12 @@
+require_relative '../llms'
+require_relative 'cli/base'
+require_relative 'cli/chat'
+require_relative 'cli/test_access'
+require_relative 'cli/test_tool_use'
+require_relative 'cli/test_image_support'
+require_relative 'cli/test_prompt_caching'
+
+module LLMs
+  module CLI
+  end
+end

data/lib/llms/conversation.rb

@@ -0,0 +1,100 @@
+require_relative './conversation_message'
+require_relative './conversation_tool_call'
+require_relative './conversation_tool_result'
+
+module LLMs
+  class Conversation
+
+    attr_reader :system_message
+
+    def initialize
+      @messages = []
+      @system_message = nil
+      @available_tools = nil
+    end
+
+    def pending?
+      !!@messages.last&.user?
+    end
+
+    def set_system_message(content)
+      raise "content is not a String" unless content.is_a?(String)
+      @system_message = content
+    end
+
+    def set_available_tools(tools)
+      @available_tools = tools
+    end
+
+    def add_user_message(content, tool_results = nil)
+      if content.is_a?(LLMs::ConversationMessage)
+        unless tool_results.nil?
+          raise "tool_results argument not allowed when adding a ConversationMessage"
+        end
+        unless content.user?
+          raise "message role must be 'user' when calling add_user_message with a ConversationMessage"
+        end
+        add_conversation_message(content)
+      else
+        unless tool_results.nil? || tool_results.all? { |tr| tr.is_a?(LLMs::ConversationToolResult) }
+          raise "tool_results argument must be an array of ConversationToolResult"
+        end
+        add_conversation_message(LLMs::ConversationMessage.new("user", content, nil, tool_results))
+      end
+    end
+
+    def add_assistant_message(content, tool_calls = nil)
+      if content.is_a?(LLMs::ConversationMessage)
+        unless tool_calls.nil?
+          raise "tool_calls argument not allowed when adding a ConversationMessage"
+        end
+        unless content.assistant?
+          raise "message role must be 'assistant' when calling add_assistant_message with a ConversationMessage"
+        end
+        add_conversation_message(content)
+      else
+        unless tool_calls.nil? || tool_calls.all? { |tc| tc.is_a?(LLMs::ConversationToolCall) }
+          raise "tool_calls argument must be an array of ConversationToolCall"
+        end
+        add_conversation_message(LLMs::ConversationMessage.new("assistant", content, tool_calls, nil))
+      end
+    end
+
+    def add_conversation_message(message)
+      raise "message is not a ConversationMessage" unless message.is_a?(LLMs::ConversationMessage)
+      @messages << message
+    end
+
+    def system_message
+      @system_message&.dup
+    end
+
+    def available_tools
+      @available_tools&.dup
+    end
+
+    def messages(include_system_message: false)
+      m = @messages.dup
+      if include_system_message && @system_message
+        m.unshift(LLMs::ConversationMessage.new("system", @system_message, nil, nil))
+      end
+      m
+    end
+
+
+
+    def last_message
+      @messages.last&.dup
+    end
+
+    def find_tool_call(tool_call_id)
+      @messages.each do |message|
+        message.tool_calls&.each do |tool_call|
+          return tool_call if tool_call.tool_call_id == tool_call_id
+        end
+      end
+      nil
+    end
+
+  end
+end

data/lib/llms/conversation_message.rb

@@ -0,0 +1,60 @@
+require_relative 'conversation_tool_call'
+require_relative 'conversation_tool_result'
+
+module LLMs
+  class ConversationMessage
+    USER_ROLE = 'user'
+    ASSISTANT_ROLE = 'assistant'
+    SYSTEM_ROLE = 'system'
+
+    attr_reader :role, :parts, :tool_calls, :tool_results
+
+    def initialize(role, content, tool_calls = nil, tool_results = nil)
+      raise "role (#{role}) is not one of the allowed values" unless role == USER_ROLE || role == ASSISTANT_ROLE || role == SYSTEM_ROLE
+      @role = role
+      @parts = if content.is_a?(String)
+        [{ text: content }]
+      elsif content.is_a?(Array)
+        content
+      else
+        raise "content (#{content}) is not a String or Array"
+      end
+      @tool_calls = tool_calls
+      @tool_results = tool_results
+    end
+
+    def text
+      if !@parts.nil?
+        text_parts = @parts.map{ |part| part[:text] }.compact
+        if !text_parts.empty?
+          text_parts.join
+        end
+      end
+    end
+
+    def images
+      if !@parts.nil?
+        @parts.map{ |part| part[:image] }.compact
+      end
+    end
+
+    def empty?
+      (@parts.nil? || @parts.empty? || self.text.nil? || self.text.empty?) &&
+        (@tool_calls.nil? || @tool_calls.empty?) &&
+        (@tool_results.nil? || @tool_results.empty?)
+    end
+
+    def user?
+      @role == USER_ROLE
+    end
+
+    def assistant?
+      @role == ASSISTANT_ROLE
+    end
+
+    ## Only for OpenAI compatible APIs
+    def system?    
+      @role == SYSTEM_ROLE
+    end
+  end
+end 

data/lib/llms/conversation_tool_call.rb

@@ -0,0 +1,14 @@
+module LLMs
+  class ConversationToolCall
+    attr_reader :index, :tool_call_id, :tool_call_type, :name, :arguments
+
+    def initialize(index, tool_call_id, tool_call_type, name, arguments)
+      raise "index is nil" if index.nil?
+      @index = index
+      @tool_call_id = tool_call_id
+      @tool_call_type = tool_call_type
+      @name = name
+      @arguments = arguments
+    end
+  end
+end