| Name | ichatbio-sdk JSON |
| Version |
0.2.2
JSON |
| download |
| home_page | None |
| Summary | A framework which allows AI agents to interact with iChatBio using the A2A protocol. |
| upload_time | 2025-07-11 20:49:25 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) [year] [fullname]
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
ai
biodiversity
ichatbio
research
science
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# iChatBio SDK
[](https://github.com/acislab/ichatbio-sdk/actions/workflows/tests.yml)
The iChatBio SDK is designed to aid in the development of agents that can communicate with iChatBio. The SDK adds a
layer of abstraction over the [A2A protocol](https://github.com/google/a2a), hiding the complexities of A2A while
exposing iChatBio-specific capabilities. Because agents designed with the iChatBio SDK make use of A2A, they are also
able to communicate with other A2A agents, though without access to services (e.g., strict data models, special messages
types, and shared persistent storage) enabled by the iChatBio ecosystem.
# Getting started
See [examples](examples) for a reference agent implementation. A standalone example agent is
available [here](https://github.com/mielliott/ichatbio-agent-example).
The iChatBio SDK is available on PyPI:
```sh
pip install ichatbio-sdk
```
Like A2A, iChatBio agents must define an agent card. Here's an example card:
```python
from ichatbio.types import AgentCard, AgentEntrypoint
card = AgentCard(
name="Friendly Agent",
description="Responds in a friendly manner.",
icon="https://example.com/icon.png",
url="http://localhost:9999",
entrypoints=[
AgentEntrypoint(
id="chat",
description="Generates a friendly reply.",
parameters=Parameters # Defined below
)
]
)
```
The card must include one or more *entrypoints*. Entrypoints define the types of interactions that are possible between
iChatBio and the agent. Each entrypoint can optionally define a set of *parameters*, which allow iChatBio to provide
structured information to the agent. This structure has a number of advantages:
* Agents can directly access parameters without the unreliable overhead of natural language processing
* Agents with strict parameter sets can only be used when the required parameters are supplied
Here's the parameter model referenced in the entrypoint above:
```python
from pydantic import BaseModel, PastDate
class Parameters(BaseModel):
birthday: PastDate
```
By using Pydantic's `PastDate` class, the birthday must both be a valid date and also be a date *in the past*. With
these constraints, the agent does not need to worry about receiving invalid parameter values and subsequent error
handling.
Here's an agent that implements the `"chat"` entrypoint:
```python
from datetime import date
from typing import override
from ichatbio.agent import IChatBioAgent
from ichatbio.agent_response import ResponseContext, IChatBioAgentProcess
from ichatbio.types import AgentCard
class FriendlyAgent(IChatBioAgent):
@override
def get_agent_card(self) -> AgentCard:
return card # The AgentCard we defined earlier
@override
async def run(self, context: ResponseContext, request: str, entrypoint: str, params: Parameters):
if entrypoint != "chat":
raise ValueError() # This should never happen
async with context.begin_process(summary="Replying") as process:
process: IChatBioAgentProcess
await process.log("Generating a friendly reply")
response = ... # Query an LLM
await process.log("Response generated", data={"response": response})
happy_birthday = params.birthday == date.today()
if happy_birthday:
await process.log("Generating a birthday surprise")
audio: bytes = ... # Generate an audio version of the response
await process.create_artifact(
mimetype="audio/mpeg",
description=f"An audio version of the response",
content=audio
)
await context.reply(
"I have generated a friendly response to the user's request. For their birthday, I also generated an"
" audio version of the response."
if happy_birthday else
"I have generated a friendly response to the user's request."
)
```
And here's a `__main__.py` to run the agent as an A2A web server:
```python
from ichatbio.server import run_agent_server
if __name__ == "__main__":
agent = FriendlyAgent()
run_agent_server(agent, host="0.0.0.0", port=9999)
```
If all went well, you should be able to find your agent card at http://localhost:9999/.well-known/agent.json.
# SDK Development
Requires Python 3.12 or higher.
Dependencies for the example agents are installed separately:
```
pip install .[example]
```
# Funding
This work is funded by grants from the National Science Foundation (DBI 2027654) and the AT&T Foundation.
Raw data
{
"_id": null,
"home_page": null,
"name": "ichatbio-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "AI, biodiversity, iChatBio, research, science",
"author": null,
"author_email": "Michael Elliott <mielliott@ufl.edu>, Manny Luciano <mlluciano@ufl.edu>",
"download_url": "https://files.pythonhosted.org/packages/74/1a/e6b4d23fc68e94d0185f36006c51897e516f4df444381618b8c8a3fe5afa/ichatbio_sdk-0.2.2.tar.gz",
"platform": null,
"description": "# iChatBio SDK\n\n[](https://github.com/acislab/ichatbio-sdk/actions/workflows/tests.yml)\n\nThe iChatBio SDK is designed to aid in the development of agents that can communicate with iChatBio. The SDK adds a\nlayer of abstraction over the [A2A protocol](https://github.com/google/a2a), hiding the complexities of A2A while\nexposing iChatBio-specific capabilities. Because agents designed with the iChatBio SDK make use of A2A, they are also\nable to communicate with other A2A agents, though without access to services (e.g., strict data models, special messages\ntypes, and shared persistent storage) enabled by the iChatBio ecosystem.\n\n# Getting started\n\nSee [examples](examples) for a reference agent implementation. A standalone example agent is\navailable [here](https://github.com/mielliott/ichatbio-agent-example).\n\nThe iChatBio SDK is available on PyPI:\n\n```sh\npip install ichatbio-sdk\n```\n\nLike A2A, iChatBio agents must define an agent card. Here's an example card:\n\n```python\nfrom ichatbio.types import AgentCard, AgentEntrypoint\n\ncard = AgentCard(\n name=\"Friendly Agent\",\n description=\"Responds in a friendly manner.\",\n icon=\"https://example.com/icon.png\",\n url=\"http://localhost:9999\",\n entrypoints=[\n AgentEntrypoint(\n id=\"chat\",\n description=\"Generates a friendly reply.\",\n parameters=Parameters # Defined below\n )\n ]\n)\n```\n\nThe card must include one or more *entrypoints*. Entrypoints define the types of interactions that are possible between\niChatBio and the agent. Each entrypoint can optionally define a set of *parameters*, which allow iChatBio to provide\nstructured information to the agent. This structure has a number of advantages:\n\n* Agents can directly access parameters without the unreliable overhead of natural language processing\n* Agents with strict parameter sets can only be used when the required parameters are supplied\n\nHere's the parameter model referenced in the entrypoint above:\n\n```python\nfrom pydantic import BaseModel, PastDate\n\n\nclass Parameters(BaseModel):\n birthday: PastDate\n```\n\nBy using Pydantic's `PastDate` class, the birthday must both be a valid date and also be a date *in the past*. With\nthese constraints, the agent does not need to worry about receiving invalid parameter values and subsequent error\nhandling.\n\nHere's an agent that implements the `\"chat\"` entrypoint:\n\n```python\nfrom datetime import date\nfrom typing import override\n\nfrom ichatbio.agent import IChatBioAgent\nfrom ichatbio.agent_response import ResponseContext, IChatBioAgentProcess\nfrom ichatbio.types import AgentCard\n\n\nclass FriendlyAgent(IChatBioAgent):\n @override\n def get_agent_card(self) -> AgentCard:\n return card # The AgentCard we defined earlier\n\n @override\n async def run(self, context: ResponseContext, request: str, entrypoint: str, params: Parameters):\n if entrypoint != \"chat\":\n raise ValueError() # This should never happen\n\n async with context.begin_process(summary=\"Replying\") as process:\n process: IChatBioAgentProcess\n\n await process.log(\"Generating a friendly reply\")\n response = ... # Query an LLM\n\n await process.log(\"Response generated\", data={\"response\": response})\n\n happy_birthday = params.birthday == date.today()\n if happy_birthday:\n await process.log(\"Generating a birthday surprise\")\n audio: bytes = ... # Generate an audio version of the response\n await process.create_artifact(\n mimetype=\"audio/mpeg\",\n description=f\"An audio version of the response\",\n content=audio\n )\n\n await context.reply(\n \"I have generated a friendly response to the user's request. For their birthday, I also generated an\"\n \" audio version of the response.\"\n if happy_birthday else\n \"I have generated a friendly response to the user's request.\"\n )\n```\n\nAnd here's a `__main__.py` to run the agent as an A2A web server:\n\n```python\nfrom ichatbio.server import run_agent_server\n\nif __name__ == \"__main__\":\n agent = FriendlyAgent()\n run_agent_server(agent, host=\"0.0.0.0\", port=9999)\n```\n\nIf all went well, you should be able to find your agent card at http://localhost:9999/.well-known/agent.json.\n\n# SDK Development\n\nRequires Python 3.12 or higher.\n\nDependencies for the example agents are installed separately:\n\n```\npip install .[example]\n```\n\n# Funding\n\nThis work is funded by grants from the National Science Foundation (DBI 2027654) and the AT&T Foundation.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) [year] [fullname]\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "A framework which allows AI agents to interact with iChatBio using the A2A protocol.",
"version": "0.2.2",
"project_urls": {
"repository": "https://github.com/acislab/ichatbio-sdk"
},
"split_keywords": [
"ai",
" biodiversity",
" ichatbio",
" research",
" science"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dcd54fbbde49b30f169b36277db9d13d9eda0762f53640b156eed296b06c45f5",
"md5": "1ca5936aaeca2ff8d0e57b5d5bb6b0ba",
"sha256": "7588c55a229692ccbb433cd06cd67e83bcfcd62e57aacd4009e191bde9e8df94"
},
"downloads": -1,
"filename": "ichatbio_sdk-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1ca5936aaeca2ff8d0e57b5d5bb6b0ba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 12076,
"upload_time": "2025-07-11T20:49:24",
"upload_time_iso_8601": "2025-07-11T20:49:24.248015Z",
"url": "https://files.pythonhosted.org/packages/dc/d5/4fbbde49b30f169b36277db9d13d9eda0762f53640b156eed296b06c45f5/ichatbio_sdk-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "741ae6b4d23fc68e94d0185f36006c51897e516f4df444381618b8c8a3fe5afa",
"md5": "5a945a414e66c229d875256be23a10c6",
"sha256": "26431390a19f69440510fda47943a6d3806d168c7c215b10f00e51a031f33135"
},
"downloads": -1,
"filename": "ichatbio_sdk-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "5a945a414e66c229d875256be23a10c6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 29448,
"upload_time": "2025-07-11T20:49:25",
"upload_time_iso_8601": "2025-07-11T20:49:25.137219Z",
"url": "https://files.pythonhosted.org/packages/74/1a/e6b4d23fc68e94d0185f36006c51897e516f4df444381618b8c8a3fe5afa/ichatbio_sdk-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 20:49:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "acislab",
"github_project": "ichatbio-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ichatbio-sdk"
}
