idun-agent-engine 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

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 (37) hide show
  1. idun_agent_engine/__init__.py +2 -25
  2. idun_agent_engine/_version.py +1 -1
  3. idun_agent_engine/agent/__init__.py +10 -0
  4. idun_agent_engine/agent/base.py +97 -0
  5. idun_agent_engine/agent/haystack/__init__.py +9 -0
  6. idun_agent_engine/agent/haystack/haystack.py +261 -0
  7. idun_agent_engine/agent/haystack/haystack_model.py +13 -0
  8. idun_agent_engine/agent/haystack/utils.py +13 -0
  9. idun_agent_engine/agent/langgraph/__init__.py +7 -0
  10. idun_agent_engine/agent/langgraph/langgraph.py +429 -0
  11. idun_agent_engine/cli/__init__.py +16 -0
  12. idun_agent_engine/core/__init__.py +11 -0
  13. idun_agent_engine/core/app_factory.py +63 -0
  14. idun_agent_engine/core/config_builder.py +456 -0
  15. idun_agent_engine/core/engine_config.py +22 -0
  16. idun_agent_engine/core/server_runner.py +146 -0
  17. idun_agent_engine/observability/__init__.py +13 -0
  18. idun_agent_engine/observability/base.py +111 -0
  19. idun_agent_engine/observability/langfuse/__init__.py +5 -0
  20. idun_agent_engine/observability/langfuse/langfuse_handler.py +72 -0
  21. idun_agent_engine/observability/phoenix/__init__.py +5 -0
  22. idun_agent_engine/observability/phoenix/phoenix_handler.py +65 -0
  23. idun_agent_engine/observability/phoenix_local/__init__.py +5 -0
  24. idun_agent_engine/observability/phoenix_local/phoenix_local_handler.py +123 -0
  25. idun_agent_engine/py.typed +0 -1
  26. idun_agent_engine/server/__init__.py +5 -0
  27. idun_agent_engine/server/dependencies.py +23 -0
  28. idun_agent_engine/server/lifespan.py +42 -0
  29. idun_agent_engine/server/routers/__init__.py +5 -0
  30. idun_agent_engine/server/routers/agent.py +68 -0
  31. idun_agent_engine/server/routers/base.py +60 -0
  32. idun_agent_engine/server/server_config.py +8 -0
  33. idun_agent_engine-0.2.1.dist-info/METADATA +278 -0
  34. idun_agent_engine-0.2.1.dist-info/RECORD +35 -0
  35. {idun_agent_engine-0.1.0.dist-info → idun_agent_engine-0.2.1.dist-info}/WHEEL +1 -1
  36. idun_agent_engine-0.1.0.dist-info/METADATA +0 -317
  37. idun_agent_engine-0.1.0.dist-info/RECORD +0 -6
@@ -0,0 +1,278 @@
1
+ Metadata-Version: 2.4
2
+ Name: idun-agent-engine
3
+ Version: 0.2.1
4
+ Summary: Python SDK and runtime to serve AI agents with FastAPI, LangGraph, and observability.
5
+ Project-URL: Homepage, https://github.com/geoffreyharrazi/idun-agent-platform
6
+ Project-URL: Repository, https://github.com/geoffreyharrazi/idun-agent-platform
7
+ Project-URL: Documentation, https://github.com/geoffreyharrazi/idun-agent-platform/tree/main/libs/idun_agent_engine
8
+ Project-URL: Issues, https://github.com/geoffreyharrazi/idun-agent-platform/issues
9
+ Author-email: Geoffrey HARRAZI <geoffreyharrazi@gmail.com>
10
+ License-Expression: MIT
11
+ Keywords: agents,fastapi,langgraph,llm,observability,sdk
12
+ Classifier: Framework :: FastAPI
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Software Development :: Libraries
19
+ Classifier: Typing :: Typed
20
+ Requires-Python: <3.14,>=3.13
21
+ Requires-Dist: ag-ui-protocol<0.2.0,>=0.1.8
22
+ Requires-Dist: aiosqlite<0.22.0,>=0.21.0
23
+ Requires-Dist: arize-phoenix-otel<1.0.0,>=0.2.0
24
+ Requires-Dist: arize-phoenix<12,>=11.22.0
25
+ Requires-Dist: fastapi<0.117.0,>=0.116.1
26
+ Requires-Dist: google-adk<2.0.0,>=1.9.0
27
+ Requires-Dist: httpx<0.29.0,>=0.28.1
28
+ Requires-Dist: idun-agent-schema<0.3.0,>=0.2.0
29
+ Requires-Dist: langchain-core<0.4.0,>=0.3.72
30
+ Requires-Dist: langchain-google-vertexai<3.0.0,>=2.0.27
31
+ Requires-Dist: langchain<0.4,>=0.3.27
32
+ Requires-Dist: langfuse-haystack>=2.3.0
33
+ Requires-Dist: langfuse==2.60.8
34
+ Requires-Dist: langgraph-checkpoint-sqlite<3.0.0,>=2.0.11
35
+ Requires-Dist: langgraph<0.7.0,>=0.6.3
36
+ Requires-Dist: openinference-instrumentation-langchain<1.0.0,>=0.1.13
37
+ Requires-Dist: pydantic<3.0.0,>=2.11.7
38
+ Requires-Dist: python-dotenv>=1.1.1
39
+ Requires-Dist: streamlit<2.0.0,>=1.47.1
40
+ Requires-Dist: uvicorn<0.36.0,>=0.35.0
41
+ Description-Content-Type: text/markdown
42
+
43
+ # Idun Agent Engine
44
+
45
+ Turn any LangGraph-based agent into a production-grade API in minutes.
46
+
47
+ Idun Agent Engine is a lightweight runtime and SDK that wraps your agent with a FastAPI server, adds streaming, structured responses, config validation, and optional observability — with zero boilerplate. Use a YAML file or a fluent builder to configure and run.
48
+
49
+ ## Installation
50
+
51
+ ```bash
52
+ pip install idun-agent-engine
53
+ ```
54
+
55
+ - Requires Python 3.13
56
+ - Ships with FastAPI, Uvicorn, LangGraph, SQLite checkpointing, and optional observability hooks
57
+
58
+ ## Quickstart
59
+
60
+ ### 1) Minimal one-liner (from a YAML config)
61
+
62
+ ```python
63
+ from idun_agent_engine.core.server_runner import run_server_from_config
64
+
65
+ run_server_from_config("config.yaml")
66
+ ```
67
+
68
+ Example `config.yaml`:
69
+
70
+ ```yaml
71
+ server:
72
+ api:
73
+ port: 8000
74
+
75
+ agent:
76
+ type: "langgraph"
77
+ config:
78
+ name: "My Example LangGraph Agent"
79
+ graph_definition: "./examples/01_basic_config_file/example_agent.py:app"
80
+ # Optional: conversation persistence
81
+ checkpointer:
82
+ type: "sqlite"
83
+ db_url: "sqlite:///example_checkpoint.db"
84
+ # Optional: provider-agnostic observability
85
+ observability:
86
+ provider: langfuse # or phoenix
87
+ enabled: true
88
+ options:
89
+ host: ${LANGFUSE_HOST}
90
+ public_key: ${LANGFUSE_PUBLIC_KEY}
91
+ secret_key: ${LANGFUSE_SECRET_KEY}
92
+ run_name: "idun-langgraph-run"
93
+ ```
94
+
95
+ Run and open docs at `http://localhost:8000/docs`.
96
+
97
+ ### 2) Programmatic setup with the fluent builder
98
+
99
+ ```python
100
+ from pathlib import Path
101
+ from idun_agent_engine import ConfigBuilder, create_app, run_server
102
+
103
+ config = (
104
+ ConfigBuilder()
105
+ .with_api_port(8000)
106
+ .with_langgraph_agent(
107
+ name="Programmatic Example Agent",
108
+ graph_definition=str(Path("./examples/02_programmatic_config/smart_agent.py:app")),
109
+ sqlite_checkpointer="programmatic_example.db",
110
+ )
111
+ .build()
112
+ )
113
+
114
+ app = create_app(engine_config=config)
115
+ run_server(app, reload=True)
116
+ ```
117
+
118
+ ## Endpoints
119
+
120
+ All servers expose these by default:
121
+
122
+ - POST `/agent/invoke`: single request/response
123
+ - POST `/agent/stream`: server-sent events stream of `ag-ui` protocol events
124
+ - GET `/health`: service health with engine version
125
+ - GET `/`: root landing with links
126
+
127
+ Invoke example:
128
+
129
+ ```bash
130
+ curl -X POST "http://localhost:8000/agent/invoke" \
131
+ -H "Content-Type: application/json" \
132
+ -d '{"query": "Hello!", "session_id": "user-123"}'
133
+ ```
134
+
135
+ Stream example:
136
+
137
+ ```bash
138
+ curl -N -X POST "http://localhost:8000/agent/stream" \
139
+ -H "Content-Type: application/json" \
140
+ -d '{"query": "Tell me a story", "session_id": "user-123"}'
141
+ ```
142
+
143
+ ## LangGraph integration
144
+
145
+ Point the engine to a `StateGraph` variable in your file using `graph_definition`:
146
+
147
+ ```python
148
+ # examples/01_basic_config_file/example_agent.py
149
+ import operator
150
+ from typing import Annotated, TypedDict
151
+ from langgraph.graph import END, StateGraph
152
+
153
+ class AgentState(TypedDict):
154
+ messages: Annotated[list, operator.add]
155
+
156
+ def greeting_node(state):
157
+ user_message = state["messages"][-1] if state["messages"] else ""
158
+ return {"messages": [("ai", f"Hello! You said: '{user_message}'")]}
159
+
160
+ graph = StateGraph(AgentState)
161
+ graph.add_node("greet", greeting_node)
162
+ graph.set_entry_point("greet")
163
+ graph.add_edge("greet", END)
164
+
165
+ # This variable name is referenced by graph_definition
166
+ app = graph
167
+ ```
168
+
169
+ Then reference it in config:
170
+
171
+ ```yaml
172
+ agent:
173
+ type: "langgraph"
174
+ config:
175
+ graph_definition: "./examples/01_basic_config_file/example_agent.py:app"
176
+ ```
177
+
178
+ Behind the scenes, the engine:
179
+
180
+ - Validates config with Pydantic models
181
+ - Loads your `StateGraph` from disk
182
+ - Optionally wires a SQLite checkpointer via `langgraph.checkpoint.sqlite`
183
+ - Exposes `invoke` and `stream` endpoints
184
+ - Bridges LangGraph events to `ag-ui` stream events
185
+
186
+ ## Observability (optional)
187
+
188
+ Enable provider-agnostic observability via the `observability` block in your agent config. Today supports Langfuse and Arize Phoenix (OpenInference) patterns; more coming soon.
189
+
190
+ ```yaml
191
+ agent:
192
+ type: "langgraph"
193
+ config:
194
+ observability:
195
+ provider: langfuse # or phoenix
196
+ enabled: true
197
+ options:
198
+ host: ${LANGFUSE_HOST}
199
+ public_key: ${LANGFUSE_PUBLIC_KEY}
200
+ secret_key: ${LANGFUSE_SECRET_KEY}
201
+ run_name: "idun-langgraph-run"
202
+ ```
203
+
204
+ ## Configuration reference
205
+
206
+ - `server.api.port` (int): HTTP port (default 8000)
207
+ - `agent.type` (enum): currently `langgraph` (CrewAI placeholder exists but not implemented)
208
+ - `agent.config.name` (str): human-readable name
209
+ - `agent.config.graph_definition` (str): absolute or relative `path/to/file.py:variable`
210
+ - `agent.config.checkpointer` (sqlite): `{ type: "sqlite", db_url: "sqlite:///file.db" }`
211
+ - `agent.config.observability` (optional): provider options as shown above
212
+
213
+ Config can be sourced by:
214
+
215
+ - `engine_config` (preferred): pass a validated `EngineConfig` to `create_app`
216
+ - `config_dict`: dict validated at runtime
217
+ - `config_path`: path to YAML; defaults to `config.yaml`
218
+
219
+ ## Examples
220
+
221
+ The `examples/` folder contains complete projects:
222
+
223
+ - `01_basic_config_file`: YAML config + simple agent
224
+ - `02_programmatic_config`: `ConfigBuilder` usage and advanced flows
225
+ - `03_minimal_setup`: one-line server from config
226
+
227
+ Run any example with Python 3.13 installed.
228
+
229
+ ## CLI and runtime helpers
230
+
231
+ Top-level imports for convenience:
232
+
233
+ ```python
234
+ from idun_agent_engine import (
235
+ create_app,
236
+ run_server,
237
+ run_server_from_config,
238
+ run_server_from_builder,
239
+ ConfigBuilder,
240
+ )
241
+ ```
242
+
243
+ - `create_app(...)` builds the FastAPI app and registers routes
244
+ - `run_server(app, ...)` runs with Uvicorn
245
+ - `run_server_from_config(path, ...)` loads config, builds app, and runs
246
+ - `run_server_from_builder(builder, ...)` builds from a builder and runs
247
+
248
+ ## Production notes
249
+
250
+ - Use a process manager (e.g., multiple Uvicorn workers behind a gateway). Note: `reload=True` is for development and incompatible with multi-worker mode.
251
+ - Mount behind a reverse proxy and enable TLS where appropriate.
252
+ - Persist conversations using the SQLite checkpointer in production or replace with a custom checkpointer when available.
253
+
254
+ ## Roadmap
255
+
256
+ - CrewAI adapter (placeholder exists, not yet implemented)
257
+ - Additional stores and checkpointers
258
+ - First-class CLI for `idun` commands
259
+
260
+ ## Contributing
261
+
262
+ Issues and PRs are welcome. See the repository:
263
+
264
+ - Repo: `https://github.com/geoffreyharrazi/idun-agent-platform`
265
+ - Package path: `libs/idun_agent_engine`
266
+ - Open an issue: `https://github.com/geoffreyharrazi/idun-agent-platform/issues`
267
+
268
+ Run locally:
269
+
270
+ ```bash
271
+ cd libs/idun_agent_engine
272
+ poetry install
273
+ poetry run pytest -q
274
+ ```
275
+
276
+ ## License
277
+
278
+ MIT — see `LICENSE` in the repo root.
@@ -0,0 +1,35 @@
1
+ idun_agent_engine/__init__.py,sha256=PhOL6foq5V0eXaoXw7xKUeCWXIWrOHrAFB8OuJnBqyM,550
2
+ idun_agent_engine/_version.py,sha256=2WvDrIJqGamS4FV-cYq6pcahq2_0MjtB-8l3Ci7hhKs,72
3
+ idun_agent_engine/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
4
+ idun_agent_engine/agent/__init__.py,sha256=foyOoRdI_04q1b6f2A5EXEpWSCKjZxpgWMWrKcsHNl8,220
5
+ idun_agent_engine/agent/base.py,sha256=xzuHIV_P7EwGyK7V2qbFUZccpm5xHaAjAkIxJL4tAwo,2856
6
+ idun_agent_engine/agent/haystack/__init__.py,sha256=y5ADrD8gWBeYIvV7tmu6OpPdJ8POHt-tyraIL7RkkWI,179
7
+ idun_agent_engine/agent/haystack/haystack.py,sha256=6xq7tOlvQxyc2w9KxikpS5S6vmXjUlK9Giwhmzg2X0w,10556
8
+ idun_agent_engine/agent/haystack/haystack_model.py,sha256=EtOYnsWRufcrQufTRMeB3V-rZVQqfnmwKwPsYGfZdCs,362
9
+ idun_agent_engine/agent/haystack/utils.py,sha256=sKRoPhzZWFw1NPsYwCockafzMBCCq3lGOrndbNE_C3M,609
10
+ idun_agent_engine/agent/langgraph/__init__.py,sha256=CoBdkp9P4livdy5B0bvj9o7ftoqKmXEr9cZv4TZLncs,107
11
+ idun_agent_engine/agent/langgraph/langgraph.py,sha256=z9-3fPeFCteHk39YsuxCdo_LaNcpVhIdF5268DutY1o,17312
12
+ idun_agent_engine/cli/__init__.py,sha256=5S_Oo7n7YwKk5VPyqborrRqKVz6lvwODQ5olj70wbnQ,490
13
+ idun_agent_engine/core/__init__.py,sha256=F0DMDlWcSWS_1dvh3xMbrdcVvZRHVnoAFFgREuSJfBI,408
14
+ idun_agent_engine/core/app_factory.py,sha256=fqxX6n4huCAsEY5lzPQPtBb7nWWaxzvhYaPsRUbZuEY,2333
15
+ idun_agent_engine/core/config_builder.py,sha256=nqlFEASHN9zlZhUnu5NAhRo2DeFkFVQ0rpx-yfnBuIw,16283
16
+ idun_agent_engine/core/engine_config.py,sha256=pHa-qiYUS7mvzW2eb6sXJoxxJCxC5fwcNUTcqiO90c0,584
17
+ idun_agent_engine/core/server_runner.py,sha256=01_aAJC-s0C5fdkEUQzwk4Vlf1SX4lsZwRTkVaJx0VE,4898
18
+ idun_agent_engine/observability/__init__.py,sha256=Jei-E8SgYulxFu5HkJz9HfcorIfQ6O7WZWGzP41ZK-4,298
19
+ idun_agent_engine/observability/base.py,sha256=uVCptXKmU_8OAvLRZliK5RqG6fOxj3a3bg18GVGMeHU,3575
20
+ idun_agent_engine/observability/langfuse/__init__.py,sha256=J8XcHV4aT1pF97k5EZiqrnYYPs9VjwfV5rUMihc5Pgk,128
21
+ idun_agent_engine/observability/langfuse/langfuse_handler.py,sha256=Hn3FxqiYDrLmGNF3JXNRBpFit_c8s2w61jl2EQO_Lco,2385
22
+ idun_agent_engine/observability/phoenix/__init__.py,sha256=tEwJYijcvSGNhFW4QJmvBcTu1D0YVJkZRTmkNCGTteM,130
23
+ idun_agent_engine/observability/phoenix/phoenix_handler.py,sha256=lGqSq-L1vmoEhAr9rbWO3KlNX5HSgBhCKESHMdZ-AfY,2539
24
+ idun_agent_engine/observability/phoenix_local/__init__.py,sha256=m9dIw1GWGKAW4wP08jxA7j4yrOg0Nxq_08bwVh8YogE,146
25
+ idun_agent_engine/observability/phoenix_local/phoenix_local_handler.py,sha256=Xd0yHNXqs42UOuXP9N_Y8sQg6dVh2qdgxGj5-4JDGiA,4254
26
+ idun_agent_engine/server/__init__.py,sha256=WaFektUsy37bNg2niAUy_TykzStukgWPnxC-t49CEwo,177
27
+ idun_agent_engine/server/dependencies.py,sha256=7yGYWxqbL4xNafpj8g8-S-TQ_GmGlPnSB_wRbW_lfMA,824
28
+ idun_agent_engine/server/lifespan.py,sha256=BC914qErOmKLNZY0-XkMkYnA0aVhLZFY7nhpKXx2D_g,1301
29
+ idun_agent_engine/server/server_config.py,sha256=RYA7Y0c5aRw_WXaX8svFUIEtTPqzn3o-WQRm2p52C6g,213
30
+ idun_agent_engine/server/routers/__init__.py,sha256=BgNzSVvHtGPGn5zhXhomwpKlDYBkeFi7xCbdcWVOgc8,102
31
+ idun_agent_engine/server/routers/agent.py,sha256=7vVzhnKXYv6yZEKP8o-ETMWhIa0Hd2qyMu63MhoiLL0,2361
32
+ idun_agent_engine/server/routers/base.py,sha256=BWueBPN7ecdNWOyQaxpdpnd6GxOcN78N8bFWN_aNgmU,1899
33
+ idun_agent_engine-0.2.1.dist-info/METADATA,sha256=MyA8VwWdZt3rfzpWGxJyBnGOb79CvDuWbXZevUQK6Nw,8536
34
+ idun_agent_engine-0.2.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
35
+ idun_agent_engine-0.2.1.dist-info/RECORD,,
@@ -1,4 +1,4 @@
1
1
  Wheel-Version: 1.0
2
- Generator: poetry-core 2.1.3
2
+ Generator: hatchling 1.27.0
3
3
  Root-Is-Purelib: true
4
4
  Tag: py3-none-any
@@ -1,317 +0,0 @@
1
- Metadata-Version: 2.3
2
- Name: idun-agent-engine
3
- Version: 0.1.0
4
- Summary: Python SDK and runtime to serve AI agents with FastAPI, LangGraph, and observability.
5
- License: MIT
6
- Keywords: agents,langgraph,fastapi,sdk,llm,observability
7
- Author: Geoffrey HARRAZI
8
- Author-email: geoffreyharrazi@gmail.com
9
- Requires-Python: >=3.13,<3.14
10
- Classifier: Framework :: FastAPI
11
- Classifier: Intended Audience :: Developers
12
- Classifier: License :: OSI Approved :: MIT License
13
- Classifier: Programming Language :: Python :: 3
14
- Classifier: Programming Language :: Python :: 3.13
15
- Classifier: Programming Language :: Python :: 3 :: Only
16
- Classifier: Topic :: Software Development :: Libraries
17
- Classifier: Typing :: Typed
18
- Requires-Dist: ag-ui-protocol (>=0.1.8,<0.2.0)
19
- Requires-Dist: aiosqlite (>=0.21.0,<0.22.0)
20
- Requires-Dist: arize-phoenix (>=11.22.0,<12.0.0)
21
- Requires-Dist: arize-phoenix-otel (>=0.2.0,<1.0.0)
22
- Requires-Dist: fastapi (>=0.116.1,<0.117.0)
23
- Requires-Dist: google-adk (>=1.9.0,<2.0.0)
24
- Requires-Dist: httpx (>=0.28.1,<0.29.0)
25
- Requires-Dist: langchain (>=0.3.27,<0.4.0)
26
- Requires-Dist: langchain-core (>=0.3.72,<0.4.0)
27
- Requires-Dist: langchain-google-vertexai (>=2.0.27,<3.0.0)
28
- Requires-Dist: langfuse (>=3.2.2,<4.0.0)
29
- Requires-Dist: langgraph (>=0.6.3,<0.7.0)
30
- Requires-Dist: langgraph-checkpoint-sqlite (>=2.0.11,<3.0.0)
31
- Requires-Dist: openinference-instrumentation-langchain (>=0.1.13,<1.0.0)
32
- Requires-Dist: pydantic (>=2.11.7,<3.0.0)
33
- Requires-Dist: streamlit (>=1.47.1,<2.0.0)
34
- Requires-Dist: uvicorn (>=0.35.0,<0.36.0)
35
- Project-URL: Documentation, https://github.com/geoffreyharrazi/idun-agent-manager/tree/main/libs/idun_agent_engine
36
- Project-URL: Homepage, https://github.com/geoffreyharrazi/idun-agent-manager
37
- Project-URL: Issues, https://github.com/geoffreyharrazi/idun-agent-manager/issues
38
- Project-URL: Repository, https://github.com/geoffreyharrazi/idun-agent-manager
39
- Description-Content-Type: text/markdown
40
-
41
- # Idun Agent Engine - User Guide
42
-
43
- The Idun Agent Engine provides a simple, powerful way to turn your conversational AI agents into production-ready web services. With just a few lines of code, you can expose your LangGraph, CrewAI, or custom agents through a FastAPI server with built-in features like streaming, persistence, and monitoring.
44
-
45
- ## 🚀 Quick Start
46
-
47
- ### Installation
48
- ```bash
49
- pip install idun-agent-engine
50
- ```
51
-
52
- ### Basic Usage
53
-
54
- ```python
55
- from idun_agent_engine import create_app, run_server
56
-
57
- # Create your FastAPI app with your agent
58
- app = create_app(config_path="config.yaml")
59
-
60
- # Run the server
61
- run_server(app, port=8000)
62
- ```
63
-
64
- That's it! Your agent is now running at `http://localhost:8000` with full API documentation at `http://localhost:8000/docs`.
65
-
66
- ## 📋 Configuration
67
-
68
- ### Option 1: YAML Configuration File
69
-
70
- Create a `config.yaml` file:
71
-
72
- ```yaml
73
- engine:
74
- api:
75
- port: 8000
76
- telemetry:
77
- provider: "langfuse"
78
-
79
- agent:
80
- type: "langgraph"
81
- config:
82
- name: "My Awesome Agent"
83
- graph_definition: "my_agent.py:graph"
84
- checkpointer:
85
- type: "sqlite"
86
- db_url: "sqlite:///agent.db"
87
- ```
88
-
89
- ### Option 2: Programmatic Configuration
90
-
91
- ```python
92
- from idun_agent_engine import ConfigBuilder, create_app, run_server
93
-
94
- config = (ConfigBuilder()
95
- .with_api_port(8080)
96
- .with_langgraph_agent(
97
- name="My Agent",
98
- graph_definition="my_agent.py:graph",
99
- sqlite_checkpointer="agent.db")
100
- .build())
101
-
102
- app = create_app(config_dict=config)
103
- run_server(app)
104
- ```
105
-
106
- ## 🤖 Supported Agent Types
107
-
108
- ### LangGraph Agents
109
-
110
- ```python
111
- # Your LangGraph agent file (my_agent.py)
112
- from langgraph.graph import StateGraph, END
113
- from typing import TypedDict
114
-
115
- class AgentState(TypedDict):
116
- messages: list
117
-
118
- def my_node(state):
119
- # Your agent logic here
120
- return {"messages": [("ai", "Hello from LangGraph!")]}
121
-
122
- graph = StateGraph(AgentState)
123
- graph.add_node("agent", my_node)
124
- graph.set_entry_point("agent")
125
- graph.add_edge("agent", END)
126
- ```
127
-
128
- ### Future Agent Types
129
- - CrewAI agents (coming soon)
130
- - AutoGen agents (coming soon)
131
- - Custom agent implementations
132
-
133
- ## 🌐 API Endpoints
134
-
135
- Once your server is running, you get these endpoints automatically:
136
-
137
- ### POST `/agent/invoke`
138
- Send a single message and get a complete response:
139
-
140
- ```bash
141
- curl -X POST "http://localhost:8000/agent/invoke" \
142
- -H "Content-Type: application/json" \
143
- -d '{
144
- "query": "Hello, how are you?",
145
- "session_id": "user-123"
146
- }'
147
- ```
148
-
149
- ### POST `/agent/stream`
150
- Stream responses in real-time:
151
-
152
- ```bash
153
- curl -X POST "http://localhost:8000/agent/stream" \
154
- -H "Content-Type: application/json" \
155
- -d '{
156
- "query": "Tell me a story",
157
- "session_id": "user-123"
158
- }'
159
- ```
160
-
161
- ### GET `/health`
162
- Health check for monitoring:
163
-
164
- ```bash
165
- curl "http://localhost:8000/health"
166
- ```
167
-
168
- ## 🔧 Advanced Usage
169
-
170
- ### Development Mode
171
- ```python
172
- # Enable auto-reload for development
173
- run_server(app, reload=True)
174
- ```
175
-
176
- ### Production Deployment
177
- ```python
178
- # Run with multiple workers for production
179
- run_server(app, workers=4, host="0.0.0.0", port=8000)
180
- ```
181
-
182
- ### One-Line Server
183
- ```python
184
- from idun_agent_engine.core.server_runner import run_server_from_config
185
-
186
- # Create and run server in one call
187
- run_server_from_config("config.yaml", port=8080, reload=True)
188
- ```
189
-
190
- ### Custom FastAPI Configuration
191
- ```python
192
- from idun_agent_engine import create_app
193
- from fastapi.middleware.cors import CORSMiddleware
194
-
195
- app = create_app("config.yaml")
196
-
197
- # Add custom middleware
198
- app.add_middleware(
199
- CORSMiddleware,
200
- allow_origins=["*"],
201
- allow_methods=["*"],
202
- allow_headers=["*"],
203
- )
204
-
205
- # Add custom routes
206
- @app.get("/custom")
207
- def custom_endpoint():
208
- return {"message": "Custom endpoint"}
209
- ```
210
-
211
- ## 🛠️ Configuration Reference
212
-
213
- ### Engine Configuration
214
- ```yaml
215
- engine:
216
- api:
217
- port: 8000 # Server port
218
- telemetry:
219
- provider: "langfuse" # Telemetry provider
220
- ```
221
-
222
- ### LangGraph Agent Configuration
223
- ```yaml
224
- agent:
225
- type: "langgraph"
226
- config:
227
- name: "Agent Name" # Human-readable name
228
- graph_definition: "path.py:graph" # Path to your graph
229
- checkpointer: # Optional persistence
230
- type: "sqlite"
231
- db_url: "sqlite:///agent.db"
232
- store: # Optional store (future)
233
- type: "memory"
234
- ```
235
-
236
- ## 📚 Examples
237
-
238
- Check out the `examples/` directory for complete working examples:
239
-
240
- - **Basic LangGraph Agent**: Simple question-answering agent
241
- - **ConfigBuilder Usage**: Programmatic configuration
242
- - **Custom Middleware**: Adding authentication and CORS
243
- - **Production Setup**: Multi-worker deployment configuration
244
-
245
- ## 🔍 Validation and Debugging
246
-
247
- ```python
248
- from idun_agent_engine.utils.validation import validate_config_dict, diagnose_setup
249
-
250
- # Validate your configuration
251
- config = {...}
252
- errors = validate_config_dict(config)
253
- if errors:
254
- print("Configuration errors:", errors)
255
-
256
- # Diagnose your setup
257
- diagnosis = diagnose_setup()
258
- print("System diagnosis:", diagnosis)
259
- ```
260
-
261
- ## 🚀 Deployment
262
-
263
- ### Docker
264
- ```dockerfile
265
- FROM python:3.11-slim
266
-
267
- COPY requirements.txt .
268
- RUN pip install -r requirements.txt
269
-
270
- COPY . .
271
-
272
- CMD ["python", "-m", "idun_agent_engine", "run", "config.yaml"]
273
- ```
274
-
275
- ### Cloud Platforms
276
- - Heroku: `Procfile` with `web: python main.py`
277
- - Railway: Deploy with one click
278
- - AWS Lambda: Use with Mangum adapter
279
- - Google Cloud Run: Deploy Docker container
280
-
281
- ## 🤝 Contributing
282
-
283
- The Idun Agent Engine is designed to be extensible. To add support for new agent frameworks:
284
-
285
- 1. Implement the `BaseAgent` interface
286
- 2. Add configuration models for your agent type
287
- 3. Register your agent in the factory
288
- 4. Submit a pull request!
289
-
290
- ## 📖 Documentation
291
-
292
- - [Full API Documentation](https://docs.idun-agent-engine.com)
293
- - [Agent Framework Guide](https://docs.idun-agent-engine.com/frameworks)
294
- - [Deployment Guide](https://docs.idun-agent-engine.com/deployment)
295
- - [Contributing Guide](https://docs.idun-agent-engine.com/contributing)
296
-
297
- ## 📄 License
298
-
299
- MIT License - see LICENSE file for details.
300
-
301
- ---
302
-
303
- ### Release & Publishing
304
-
305
- This package is built with Poetry. To publish a new release to PyPI:
306
-
307
- 1. Update version in `pyproject.toml`.
308
- 2. Commit and tag with the pattern `idun-agent-engine-vX.Y.Z`.
309
- 3. Push the tag to GitHub. The `Publish idun-agent-engine` workflow will build and publish to PyPI using `PYPI_API_TOKEN` secret.
310
-
311
- Manual build (optional):
312
-
313
- ```bash
314
- cd libs/idun_agent_engine
315
- poetry build
316
- ```
317
-
@@ -1,6 +0,0 @@
1
- idun_agent_engine/__init__.py,sha256=26POsr5dcEKjaasCyghn5xq1iBnEzyripAj-OaKhFrI,1471
2
- idun_agent_engine/_version.py,sha256=6TpxMitT_P6rTobGO07lWrTBf1CNK8giofFXhNSBnS0,72
3
- idun_agent_engine/py.typed,sha256=cJop7713r6RxY0ks5pWo7USgH7UFlZsBhyByVzA4q_o,61
4
- idun_agent_engine-0.1.0.dist-info/METADATA,sha256=2he27WE8SahXhQPOj5rTQDLJuCtc535x3c-IC4zozzU,8306
5
- idun_agent_engine-0.1.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
6
- idun_agent_engine-0.1.0.dist-info/RECORD,,