hippodb-agent-sdk 1.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. hippodb_agent_sdk-1.2.0/LICENSE +75 -0
  2. hippodb_agent_sdk-1.2.0/PKG-INFO +355 -0
  3. hippodb_agent_sdk-1.2.0/README.md +245 -0
  4. hippodb_agent_sdk-1.2.0/pyproject.toml +52 -0
  5. hippodb_agent_sdk-1.2.0/setup.cfg +4 -0
  6. hippodb_agent_sdk-1.2.0/src/hippodb_agent/__init__.py +22 -0
  7. hippodb_agent_sdk-1.2.0/src/hippodb_agent/config.py +168 -0
  8. hippodb_agent_sdk-1.2.0/src/hippodb_agent/core/__init__.py +0 -0
  9. hippodb_agent_sdk-1.2.0/src/hippodb_agent/core/agent.py +815 -0
  10. hippodb_agent_sdk-1.2.0/src/hippodb_agent/core/llm.py +440 -0
  11. hippodb_agent_sdk-1.2.0/src/hippodb_agent/core/role.py +58 -0
  12. hippodb_agent_sdk-1.2.0/src/hippodb_agent/core/runner.py +506 -0
  13. hippodb_agent_sdk-1.2.0/src/hippodb_agent/creator/__init__.py +6 -0
  14. hippodb_agent_sdk-1.2.0/src/hippodb_agent/creator/__main__.py +5 -0
  15. hippodb_agent_sdk-1.2.0/src/hippodb_agent/creator/generators.py +758 -0
  16. hippodb_agent_sdk-1.2.0/src/hippodb_agent/creator/main.py +40 -0
  17. hippodb_agent_sdk-1.2.0/src/hippodb_agent/creator/openapi_parser.py +358 -0
  18. hippodb_agent_sdk-1.2.0/src/hippodb_agent/creator/role.py +104 -0
  19. hippodb_agent_sdk-1.2.0/src/hippodb_agent/creator/state.py +115 -0
  20. hippodb_agent_sdk-1.2.0/src/hippodb_agent/creator/tools.py +762 -0
  21. hippodb_agent_sdk-1.2.0/src/hippodb_agent/defaults.env +21 -0
  22. hippodb_agent_sdk-1.2.0/src/hippodb_agent/feedback/__init__.py +6 -0
  23. hippodb_agent_sdk-1.2.0/src/hippodb_agent/feedback/classifier.py +85 -0
  24. hippodb_agent_sdk-1.2.0/src/hippodb_agent/gateway/__init__.py +22 -0
  25. hippodb_agent_sdk-1.2.0/src/hippodb_agent/gateway/audit.py +113 -0
  26. hippodb_agent_sdk-1.2.0/src/hippodb_agent/gateway/compliance.py +427 -0
  27. hippodb_agent_sdk-1.2.0/src/hippodb_agent/gateway/gateway.py +505 -0
  28. hippodb_agent_sdk-1.2.0/src/hippodb_agent/gateway/masker.py +307 -0
  29. hippodb_agent_sdk-1.2.0/src/hippodb_agent/gateway/policies.py +69 -0
  30. hippodb_agent_sdk-1.2.0/src/hippodb_agent/gateway/summarizer.py +146 -0
  31. hippodb_agent_sdk-1.2.0/src/hippodb_agent/gateway/tokens.py +94 -0
  32. hippodb_agent_sdk-1.2.0/src/hippodb_agent/logging/__init__.py +0 -0
  33. hippodb_agent_sdk-1.2.0/src/hippodb_agent/logging/setup.py +130 -0
  34. hippodb_agent_sdk-1.2.0/src/hippodb_agent/memory/__init__.py +0 -0
  35. hippodb_agent_sdk-1.2.0/src/hippodb_agent/memory/audit.py +219 -0
  36. hippodb_agent_sdk-1.2.0/src/hippodb_agent/memory/client.py +1190 -0
  37. hippodb_agent_sdk-1.2.0/src/hippodb_agent/memory/conflicts.py +171 -0
  38. hippodb_agent_sdk-1.2.0/src/hippodb_agent/memory/formatter.py +366 -0
  39. hippodb_agent_sdk-1.2.0/src/hippodb_agent/memory/instructions.py +20 -0
  40. hippodb_agent_sdk-1.2.0/src/hippodb_agent/memory/seed.py +281 -0
  41. hippodb_agent_sdk-1.2.0/src/hippodb_agent/monitor/__init__.py +25 -0
  42. hippodb_agent_sdk-1.2.0/src/hippodb_agent/monitor/brain_report.py +371 -0
  43. hippodb_agent_sdk-1.2.0/src/hippodb_agent/monitor/metrics.py +164 -0
  44. hippodb_agent_sdk-1.2.0/src/hippodb_agent/monitor/neuro_monitor.py +385 -0
  45. hippodb_agent_sdk-1.2.0/src/hippodb_agent/network/__init__.py +6 -0
  46. hippodb_agent_sdk-1.2.0/src/hippodb_agent/network/client.py +416 -0
  47. hippodb_agent_sdk-1.2.0/src/hippodb_agent/network/control.py +240 -0
  48. hippodb_agent_sdk-1.2.0/src/hippodb_agent/network/enterprise.py +29 -0
  49. hippodb_agent_sdk-1.2.0/src/hippodb_agent/network/models.py +59 -0
  50. hippodb_agent_sdk-1.2.0/src/hippodb_agent/network/safety.py +147 -0
  51. hippodb_agent_sdk-1.2.0/src/hippodb_agent/network/telemetry.py +264 -0
  52. hippodb_agent_sdk-1.2.0/src/hippodb_agent/network/tools.py +147 -0
  53. hippodb_agent_sdk-1.2.0/src/hippodb_agent/prompt/__init__.py +5 -0
  54. hippodb_agent_sdk-1.2.0/src/hippodb_agent/prompt/composer.py +101 -0
  55. hippodb_agent_sdk-1.2.0/src/hippodb_agent/rules/__init__.py +94 -0
  56. hippodb_agent_sdk-1.2.0/src/hippodb_agent/rules/compiler.py +387 -0
  57. hippodb_agent_sdk-1.2.0/src/hippodb_agent/rules/dsl.py +359 -0
  58. hippodb_agent_sdk-1.2.0/src/hippodb_agent/rules/enforcer.py +331 -0
  59. hippodb_agent_sdk-1.2.0/src/hippodb_agent/rules/interpreter.py +228 -0
  60. hippodb_agent_sdk-1.2.0/src/hippodb_agent/rules/sandbox.py +343 -0
  61. hippodb_agent_sdk-1.2.0/src/hippodb_agent/terminal.py +124 -0
  62. hippodb_agent_sdk-1.2.0/src/hippodb_agent/tools/__init__.py +0 -0
  63. hippodb_agent_sdk-1.2.0/src/hippodb_agent/tools/base.py +165 -0
  64. hippodb_agent_sdk-1.2.0/src/hippodb_agent/tools/builtin.py +1557 -0
  65. hippodb_agent_sdk-1.2.0/src/hippodb_agent/tools/calc_tools.py +831 -0
  66. hippodb_agent_sdk-1.2.0/src/hippodb_agent/tools/discovery.py +392 -0
  67. hippodb_agent_sdk-1.2.0/src/hippodb_agent/tools/os_tools.py +427 -0
  68. hippodb_agent_sdk-1.2.0/src/hippodb_agent/tools/registry.py +451 -0
  69. hippodb_agent_sdk-1.2.0/src/hippodb_agent/tuning/__init__.py +0 -0
  70. hippodb_agent_sdk-1.2.0/src/hippodb_agent/tuning/applier.py +65 -0
  71. hippodb_agent_sdk-1.2.0/src/hippodb_agent/tuning/diagnoser.py +129 -0
  72. hippodb_agent_sdk-1.2.0/src/hippodb_agent/tuning/models.py +115 -0
  73. hippodb_agent_sdk-1.2.0/src/hippodb_agent/tuning/orchestrator.py +229 -0
  74. hippodb_agent_sdk-1.2.0/src/hippodb_agent/tuning/planner.py +113 -0
  75. hippodb_agent_sdk-1.2.0/src/hippodb_agent/tuning/simulator.py +106 -0
  76. hippodb_agent_sdk-1.2.0/src/hippodb_agent/tuning/tracker.py +97 -0
  77. hippodb_agent_sdk-1.2.0/src/hippodb_agent/tuning/validator.py +106 -0
  78. hippodb_agent_sdk-1.2.0/src/hippodb_agent_sdk.egg-info/PKG-INFO +355 -0
  79. hippodb_agent_sdk-1.2.0/src/hippodb_agent_sdk.egg-info/SOURCES.txt +80 -0
  80. hippodb_agent_sdk-1.2.0/src/hippodb_agent_sdk.egg-info/dependency_links.txt +1 -0
  81. hippodb_agent_sdk-1.2.0/src/hippodb_agent_sdk.egg-info/requires.txt +15 -0
  82. hippodb_agent_sdk-1.2.0/src/hippodb_agent_sdk.egg-info/top_level.txt +1 -0
@@ -0,0 +1,75 @@
1
+ # PolyForm Noncommercial License 1.0.0
2
+
3
+ <https://polyformproject.org/licenses/noncommercial/1.0.0>
4
+
5
+ Required Notice: Copyright 2026 Luthen (https://luthen.ai/)
6
+
7
+ ## Acceptance
8
+
9
+ In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
10
+
11
+ ## Copyright License
12
+
13
+ The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
14
+
15
+ ## Distribution License
16
+
17
+ The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
18
+
19
+ ## Notices
20
+
21
+ You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
22
+
23
+ > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
24
+
25
+ ## Changes and New Works License
26
+
27
+ The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
28
+
29
+ ## Patent License
30
+
31
+ The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
32
+
33
+ ## Noncommercial Purposes
34
+
35
+ Any noncommercial purpose is a permitted purpose.
36
+
37
+ ## Personal Uses
38
+
39
+ Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
40
+
41
+ ## Noncommercial Organizations
42
+
43
+ Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
44
+
45
+ ## Fair Use
46
+
47
+ You may have "fair use" rights for the software under the law. These terms do not limit them.
48
+
49
+ ## No Other Rights
50
+
51
+ These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
52
+
53
+ ## Patent Defense
54
+
55
+ If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
56
+
57
+ ## Violations
58
+
59
+ The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
60
+
61
+ ## No Liability
62
+
63
+ ***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
64
+
65
+ ## Definitions
66
+
67
+ The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
68
+
69
+ **You** refers to the individual or entity agreeing to these terms.
70
+
71
+ **Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
72
+
73
+ **Your licenses** are all the licenses granted to you for the software under these terms.
74
+
75
+ **Use** means anything you do with the software requiring one of your licenses.
@@ -0,0 +1,355 @@
1
+ Metadata-Version: 2.4
2
+ Name: hippodb-agent-sdk
3
+ Version: 1.2.0
4
+ Summary: Agent development kit for building self-tuning AI agents with HippoDb biological memory
5
+ Author-email: darshana@behaviol.com
6
+ Maintainer-email: chamika@behaviol.com, sandun@behaviol.com
7
+ License: # PolyForm Noncommercial License 1.0.0
8
+
9
+ <https://polyformproject.org/licenses/noncommercial/1.0.0>
10
+
11
+ Required Notice: Copyright 2026 Luthen (https://luthen.ai/)
12
+
13
+ ## Acceptance
14
+
15
+ In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
16
+
17
+ ## Copyright License
18
+
19
+ The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
20
+
21
+ ## Distribution License
22
+
23
+ The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
24
+
25
+ ## Notices
26
+
27
+ You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
28
+
29
+ > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
30
+
31
+ ## Changes and New Works License
32
+
33
+ The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
34
+
35
+ ## Patent License
36
+
37
+ The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
38
+
39
+ ## Noncommercial Purposes
40
+
41
+ Any noncommercial purpose is a permitted purpose.
42
+
43
+ ## Personal Uses
44
+
45
+ Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
46
+
47
+ ## Noncommercial Organizations
48
+
49
+ Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
50
+
51
+ ## Fair Use
52
+
53
+ You may have "fair use" rights for the software under the law. These terms do not limit them.
54
+
55
+ ## No Other Rights
56
+
57
+ These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
58
+
59
+ ## Patent Defense
60
+
61
+ If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
62
+
63
+ ## Violations
64
+
65
+ The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
66
+
67
+ ## No Liability
68
+
69
+ ***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
70
+
71
+ ## Definitions
72
+
73
+ The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
74
+
75
+ **You** refers to the individual or entity agreeing to these terms.
76
+
77
+ **Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
78
+
79
+ **Your licenses** are all the licenses granted to you for the software under these terms.
80
+
81
+ **Use** means anything you do with the software requiring one of your licenses.
82
+
83
+ Project-URL: Homepage, https://luthen.ai/
84
+ Keywords: ai-agent,agent-sdk,llm,memory,hippodb,tool-use
85
+ Classifier: Development Status :: 5 - Production/Stable
86
+ Classifier: Intended Audience :: Developers
87
+ Classifier: License :: Other/Proprietary License
88
+ Classifier: Operating System :: OS Independent
89
+ Classifier: Programming Language :: Python :: 3
90
+ Classifier: Programming Language :: Python :: 3.12
91
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
92
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
93
+ Requires-Python: >=3.12
94
+ Description-Content-Type: text/markdown
95
+ License-File: LICENSE
96
+ Requires-Dist: anthropic>=0.40.0
97
+ Requires-Dist: httpx>=0.27.0
98
+ Requires-Dist: litellm>=1.83.14
99
+ Requires-Dist: pydantic>=2.0.0
100
+ Requires-Dist: pydantic-settings>=2.0.0
101
+ Requires-Dist: python-dotenv>=1.0.0
102
+ Requires-Dist: pyyaml>=6.0.3
103
+ Requires-Dist: rich>=13.0.0
104
+ Provides-Extra: dev
105
+ Requires-Dist: pytest; extra == "dev"
106
+ Requires-Dist: pytest-asyncio; extra == "dev"
107
+ Provides-Extra: network
108
+ Requires-Dist: nats-py>=2.9.0; extra == "network"
109
+ Dynamic: license-file
110
+
111
+ # HippoDb Agent SDK
112
+
113
+ Python SDK for building self-tuning AI agents backed by HippoDb.
114
+
115
+ Homepage: [https://luthen.ai/](https://luthen.ai/)
116
+
117
+ This package is designed for developers who want to build custom agents with:
118
+ - an LLM tool-use loop
119
+ - persistent memory in HippoDb
120
+ - configurable business tools
121
+ - optional rule enforcement, tuning, gateway, and networking features
122
+
123
+ ## What This SDK Provides
124
+
125
+ - `AgentRunner` to boot and run an agent
126
+ - `RoleConfig` to define agent identity and prompt behavior
127
+ - `BaseTool` to define business-domain tools
128
+ - `AgentSettings` to configure runtime behavior
129
+ - built-in memory, OS, and calculator tools
130
+ - HippoDb-backed memory client and memory seeding support
131
+
132
+ ## Core Concepts
133
+
134
+ ### 1. Role
135
+
136
+ A role defines what the agent is, which tools it can see, and how it should behave.
137
+
138
+ ### 2. Tools
139
+
140
+ Tools are Python classes that inherit from `BaseTool`. They are how the agent interacts with external systems.
141
+
142
+ ### 3. Runner
143
+
144
+ `AgentRunner` wires together the LLM, tools, HippoDb, configuration, and terminal runtime.
145
+
146
+ ### 4. Memory
147
+
148
+ HippoDb acts as the persistent memory layer for concepts, rules, and conversation continuity.
149
+
150
+ ## Installation
151
+
152
+ ```bash
153
+ pip install hippodb-agent-sdk
154
+ ```
155
+
156
+ For local development against a source checkout:
157
+
158
+ ```bash
159
+ pip install -e .
160
+ ```
161
+
162
+ ## Configuration
163
+
164
+ Configuration is loaded from:
165
+ 1. SDK defaults in `src/hippodb_agent/defaults.env`
166
+ 2. local `.env`
167
+ 3. environment variables
168
+
169
+ Important settings include:
170
+ - `LLM_API_KEY`
171
+ - `ANTHROPIC_API_KEY`
172
+ - `HIPPODB_URL`
173
+ - `MODEL`
174
+
175
+ Example `.env`:
176
+
177
+ ```env
178
+ LLM_API_KEY=your_key_here
179
+ HIPPODB_URL=http://localhost:7700
180
+ MODEL=anthropic/claude-sonnet-4-20250514
181
+ ```
182
+
183
+ ## Minimal Example
184
+
185
+ Create a small agent with one custom tool.
186
+
187
+ ### `tools.py`
188
+
189
+ ```python
190
+ from hippodb_agent import BaseTool
191
+
192
+
193
+ class HelloTool(BaseTool):
194
+ name = "demo_hello"
195
+ description = "Return a hello message"
196
+ input_schema = {
197
+ "type": "object",
198
+ "properties": {},
199
+ "required": [],
200
+ }
201
+
202
+ async def execute(self, inp: dict) -> dict:
203
+ return {"message": "hello from HippoDb Agent SDK"}
204
+ ```
205
+
206
+ ### `role.py`
207
+
208
+ ```python
209
+ from hippodb_agent import RoleConfig
210
+
211
+
212
+ MY_ROLE = RoleConfig(
213
+ name="demo_agent",
214
+ display_name="Demo Agent",
215
+ tool_scopes=["demo_"],
216
+ fabric="demo_agent",
217
+ system_prompt="You are a helpful demo agent.\n\n{manifest}",
218
+ )
219
+ ```
220
+
221
+ ### `main.py`
222
+
223
+ ```python
224
+ from hippodb_agent import AgentRunner
225
+ from role import MY_ROLE
226
+ from tools import HelloTool
227
+
228
+
229
+ runner = AgentRunner(
230
+ role=MY_ROLE,
231
+ business_tools=[HelloTool],
232
+ )
233
+
234
+
235
+ if __name__ == "__main__":
236
+ runner.start()
237
+ ```
238
+
239
+ Run it with:
240
+
241
+ ```bash
242
+ python main.py
243
+ ```
244
+
245
+ ## Building a New Agent
246
+
247
+ For a typical agent project, you usually create:
248
+ - `tools.py` for business-domain tools
249
+ - `role.py` for `RoleConfig`
250
+ - `main.py` as the startup entry point
251
+ - `seed.yaml` for pre-education
252
+ - `test_suite.py` or tests for validation
253
+
254
+ ### Example Tool
255
+
256
+ ```python
257
+ from hippodb_agent import BaseTool
258
+
259
+
260
+ class ListEmployees(BaseTool):
261
+ name = "hr_list_employees"
262
+ description = "List all employees"
263
+ input_schema = {"type": "object", "properties": {}, "required": []}
264
+ backend = "hr"
265
+
266
+ async def execute(self, inp: dict) -> dict:
267
+ r = await self.api.get("/employees")
268
+ r.raise_for_status()
269
+ return r.json()
270
+ ```
271
+
272
+ ### Example Runner With Backend
273
+
274
+ ```python
275
+ from hippodb_agent import AgentRunner
276
+ from role import MY_ROLE
277
+ from tools import ListEmployees
278
+
279
+
280
+ runner = AgentRunner(
281
+ role=MY_ROLE,
282
+ business_tools=[ListEmployees],
283
+ api_base_url="http://localhost:9000",
284
+ seed_file="seed.yaml",
285
+ )
286
+
287
+
288
+ if __name__ == "__main__":
289
+ runner.start()
290
+ ```
291
+
292
+ ## Public SDK Surface
293
+
294
+ The intended primary imports are:
295
+
296
+ ```python
297
+ from hippodb_agent import (
298
+ AgentSettings,
299
+ RoleConfig,
300
+ AgentRunner,
301
+ BaseTool,
302
+ ApiClients,
303
+ )
304
+ ```
305
+
306
+ Additional helper exports currently include:
307
+ - `get_os_tools`
308
+ - `get_calc_tools`
309
+ - `BaseMemoryFormatter`
310
+ - `get_formatter`
311
+ - `DataGateway`
312
+ - `MaskStrategy`
313
+ - `FieldPolicy`
314
+ - `AgentNetwork`
315
+
316
+ ## Runtime Behavior
317
+
318
+ Installing this package does not start any worker or background service.
319
+
320
+ Runtime behavior begins only when your application starts an agent, typically through `AgentRunner.start()`.
321
+
322
+ Depending on configuration, startup may:
323
+ - connect to HippoDb
324
+ - create or reuse a fabric
325
+ - seed memory from `seed.yaml`
326
+ - start internal scheduler tasks
327
+ - connect to the optional agent network
328
+
329
+ ## Notes
330
+
331
+ - This repository currently includes some optional subsystems beyond the core SDK, such as networking, gateway/compliance, tuning, monitoring, and sleep orchestration.
332
+ - The primary use of the package is as an SDK for building custom agents.
333
+ - Bundled utility applications may exist in the repository, but they are not required for SDK usage.
334
+
335
+ ## Development
336
+
337
+ Useful local commands:
338
+
339
+ ```bash
340
+ pip install -e .[dev]
341
+ pytest
342
+ ```
343
+
344
+ ## License
345
+
346
+ This SDK is distributed under the **PolyForm Noncommercial License 1.0.0**. In short:
347
+
348
+ - Free to install, run, modify, and evaluate for any noncommercial purpose (personal projects, research, internal evaluation, etc.)
349
+ - Any commercial use requires a separate license from us.
350
+
351
+ See [LICENSE](LICENSE) for the full terms.
352
+
353
+ For commercial licensing inquiries, contact **darshana@behaviol.com**.
354
+
355
+ This technology is created and owned by Behaviol Pvt Ltd, distributed under the product name Luthen ([https://luthen.ai/](https://luthen.ai/)).
@@ -0,0 +1,245 @@
1
+ # HippoDb Agent SDK
2
+
3
+ Python SDK for building self-tuning AI agents backed by HippoDb.
4
+
5
+ Homepage: [https://luthen.ai/](https://luthen.ai/)
6
+
7
+ This package is designed for developers who want to build custom agents with:
8
+ - an LLM tool-use loop
9
+ - persistent memory in HippoDb
10
+ - configurable business tools
11
+ - optional rule enforcement, tuning, gateway, and networking features
12
+
13
+ ## What This SDK Provides
14
+
15
+ - `AgentRunner` to boot and run an agent
16
+ - `RoleConfig` to define agent identity and prompt behavior
17
+ - `BaseTool` to define business-domain tools
18
+ - `AgentSettings` to configure runtime behavior
19
+ - built-in memory, OS, and calculator tools
20
+ - HippoDb-backed memory client and memory seeding support
21
+
22
+ ## Core Concepts
23
+
24
+ ### 1. Role
25
+
26
+ A role defines what the agent is, which tools it can see, and how it should behave.
27
+
28
+ ### 2. Tools
29
+
30
+ Tools are Python classes that inherit from `BaseTool`. They are how the agent interacts with external systems.
31
+
32
+ ### 3. Runner
33
+
34
+ `AgentRunner` wires together the LLM, tools, HippoDb, configuration, and terminal runtime.
35
+
36
+ ### 4. Memory
37
+
38
+ HippoDb acts as the persistent memory layer for concepts, rules, and conversation continuity.
39
+
40
+ ## Installation
41
+
42
+ ```bash
43
+ pip install hippodb-agent-sdk
44
+ ```
45
+
46
+ For local development against a source checkout:
47
+
48
+ ```bash
49
+ pip install -e .
50
+ ```
51
+
52
+ ## Configuration
53
+
54
+ Configuration is loaded from:
55
+ 1. SDK defaults in `src/hippodb_agent/defaults.env`
56
+ 2. local `.env`
57
+ 3. environment variables
58
+
59
+ Important settings include:
60
+ - `LLM_API_KEY`
61
+ - `ANTHROPIC_API_KEY`
62
+ - `HIPPODB_URL`
63
+ - `MODEL`
64
+
65
+ Example `.env`:
66
+
67
+ ```env
68
+ LLM_API_KEY=your_key_here
69
+ HIPPODB_URL=http://localhost:7700
70
+ MODEL=anthropic/claude-sonnet-4-20250514
71
+ ```
72
+
73
+ ## Minimal Example
74
+
75
+ Create a small agent with one custom tool.
76
+
77
+ ### `tools.py`
78
+
79
+ ```python
80
+ from hippodb_agent import BaseTool
81
+
82
+
83
+ class HelloTool(BaseTool):
84
+ name = "demo_hello"
85
+ description = "Return a hello message"
86
+ input_schema = {
87
+ "type": "object",
88
+ "properties": {},
89
+ "required": [],
90
+ }
91
+
92
+ async def execute(self, inp: dict) -> dict:
93
+ return {"message": "hello from HippoDb Agent SDK"}
94
+ ```
95
+
96
+ ### `role.py`
97
+
98
+ ```python
99
+ from hippodb_agent import RoleConfig
100
+
101
+
102
+ MY_ROLE = RoleConfig(
103
+ name="demo_agent",
104
+ display_name="Demo Agent",
105
+ tool_scopes=["demo_"],
106
+ fabric="demo_agent",
107
+ system_prompt="You are a helpful demo agent.\n\n{manifest}",
108
+ )
109
+ ```
110
+
111
+ ### `main.py`
112
+
113
+ ```python
114
+ from hippodb_agent import AgentRunner
115
+ from role import MY_ROLE
116
+ from tools import HelloTool
117
+
118
+
119
+ runner = AgentRunner(
120
+ role=MY_ROLE,
121
+ business_tools=[HelloTool],
122
+ )
123
+
124
+
125
+ if __name__ == "__main__":
126
+ runner.start()
127
+ ```
128
+
129
+ Run it with:
130
+
131
+ ```bash
132
+ python main.py
133
+ ```
134
+
135
+ ## Building a New Agent
136
+
137
+ For a typical agent project, you usually create:
138
+ - `tools.py` for business-domain tools
139
+ - `role.py` for `RoleConfig`
140
+ - `main.py` as the startup entry point
141
+ - `seed.yaml` for pre-education
142
+ - `test_suite.py` or tests for validation
143
+
144
+ ### Example Tool
145
+
146
+ ```python
147
+ from hippodb_agent import BaseTool
148
+
149
+
150
+ class ListEmployees(BaseTool):
151
+ name = "hr_list_employees"
152
+ description = "List all employees"
153
+ input_schema = {"type": "object", "properties": {}, "required": []}
154
+ backend = "hr"
155
+
156
+ async def execute(self, inp: dict) -> dict:
157
+ r = await self.api.get("/employees")
158
+ r.raise_for_status()
159
+ return r.json()
160
+ ```
161
+
162
+ ### Example Runner With Backend
163
+
164
+ ```python
165
+ from hippodb_agent import AgentRunner
166
+ from role import MY_ROLE
167
+ from tools import ListEmployees
168
+
169
+
170
+ runner = AgentRunner(
171
+ role=MY_ROLE,
172
+ business_tools=[ListEmployees],
173
+ api_base_url="http://localhost:9000",
174
+ seed_file="seed.yaml",
175
+ )
176
+
177
+
178
+ if __name__ == "__main__":
179
+ runner.start()
180
+ ```
181
+
182
+ ## Public SDK Surface
183
+
184
+ The intended primary imports are:
185
+
186
+ ```python
187
+ from hippodb_agent import (
188
+ AgentSettings,
189
+ RoleConfig,
190
+ AgentRunner,
191
+ BaseTool,
192
+ ApiClients,
193
+ )
194
+ ```
195
+
196
+ Additional helper exports currently include:
197
+ - `get_os_tools`
198
+ - `get_calc_tools`
199
+ - `BaseMemoryFormatter`
200
+ - `get_formatter`
201
+ - `DataGateway`
202
+ - `MaskStrategy`
203
+ - `FieldPolicy`
204
+ - `AgentNetwork`
205
+
206
+ ## Runtime Behavior
207
+
208
+ Installing this package does not start any worker or background service.
209
+
210
+ Runtime behavior begins only when your application starts an agent, typically through `AgentRunner.start()`.
211
+
212
+ Depending on configuration, startup may:
213
+ - connect to HippoDb
214
+ - create or reuse a fabric
215
+ - seed memory from `seed.yaml`
216
+ - start internal scheduler tasks
217
+ - connect to the optional agent network
218
+
219
+ ## Notes
220
+
221
+ - This repository currently includes some optional subsystems beyond the core SDK, such as networking, gateway/compliance, tuning, monitoring, and sleep orchestration.
222
+ - The primary use of the package is as an SDK for building custom agents.
223
+ - Bundled utility applications may exist in the repository, but they are not required for SDK usage.
224
+
225
+ ## Development
226
+
227
+ Useful local commands:
228
+
229
+ ```bash
230
+ pip install -e .[dev]
231
+ pytest
232
+ ```
233
+
234
+ ## License
235
+
236
+ This SDK is distributed under the **PolyForm Noncommercial License 1.0.0**. In short:
237
+
238
+ - Free to install, run, modify, and evaluate for any noncommercial purpose (personal projects, research, internal evaluation, etc.)
239
+ - Any commercial use requires a separate license from us.
240
+
241
+ See [LICENSE](LICENSE) for the full terms.
242
+
243
+ For commercial licensing inquiries, contact **darshana@behaviol.com**.
244
+
245
+ This technology is created and owned by Behaviol Pvt Ltd, distributed under the product name Luthen ([https://luthen.ai/](https://luthen.ai/)).