agentir-langgraph-annotation 0.1.0__tar.gz

agentir_langgraph_annotation-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krish Modi
+
+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.

agentir_langgraph_annotation-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: agentir-langgraph-annotation
+Version: 0.1.0
+Summary: Public AgentIR SDK, decorators, contract tooling, and client logging helpers.
+License-Expression: MIT
+License-File: LICENSE
+Dynamic: license-file

agentir_langgraph_annotation-0.1.0/README.md

@@ -0,0 +1,265 @@
+# AgentIR SDK
+
+Copy-ready SDK for annotating LangGraph nodes so external schedulers and analyzers can reason about your graph. Install from this tree (or move `agentir_sdk/` into its own repo and `pip install -e` there) when running AgentIR graph benchmarks.
+
+## Purpose
+
+- Annotate graph nodes with read/write metadata.
+- Build scheduler-facing graph contracts.
+- Propagate RID and node-name metadata into model calls.
+- Bind scheduler headers into custom `.invoke()` wrappers.
+- Provide lightweight client-side logging helpers.
+
+## What you get
+
+With decorators plus `GraphProxy`, you can expose:
+
+- Which state keys each node writes.
+- Which state keys each LLM call reads.
+- Static prompt components per call.
+- Conditional routing structure.
+- A machine-readable graph contract (`Contract.to_dict()`).
+
+## Install
+
+```bash
+pip install -e <path-to-agentir-sdk-repo>
+```
+
+## Package layout
+
+| Area | Location |
+|------|----------|
+| `@writes`, `@llm_call` | `agentir_sdk/decorators.py` |
+| Contract data structures | `agentir_sdk/contract.py` |
+| `GraphProxy` | `agentir_sdk/graph_proxy.py` |
+| RID helpers | `agentir_sdk/rid.py` |
+| Client logging | `agentir_sdk/client_logger.py` |
+
+## Core API
+
+### `@writes(*keys: str)`
+
+Declare state keys produced by a node.
+
+```python
+from agentir_sdk.decorators import writes
+
+@writes("draft", "messages")
+def composer(state, config=None):
+    ...
+    return {"draft": text, "messages": [...]}
+```
+
+**Guidance**
+
+- List only keys the node really produces.
+- Keep names aligned with your `TypedDict` state.
+- Include keys even if they are sometimes empty.
+
+**Scheduling implication:** `writes` defines outputs that downstream nodes may depend on.
+
+### `@llm_call(model=None, reads=None, static_vars=None)`
+
+Declare one LLM call site inside a node.
+
+```python
+from agentir_sdk.decorators import llm_call
+
+@llm_call(
+    model="gpt-4o-mini",
+    reads=["task_brief", "research_notes"],
+    static_vars=["You are a precise writing assistant."]
+)
+def composer(state, config=None):
+    ...
+```
+
+**Parameters**
+
+- `model`: logical model identifier.
+- `reads`: state keys used to build that prompt.
+- `static_vars`: static prompt constants/templates.
+
+You can stack multiple `@llm_call` decorators on one function for multiple call sites.
+
+**Scheduling implications**
+
+- `reads` exposes data dependencies for that call.
+- `model` and `static_vars` provide stable metadata about call shape.
+
+## Build graphs with `GraphProxy`
+
+Use `GraphProxy` as the builder wrapper around `StateGraph`.
+
+```python
+from langgraph.graph import StateGraph
+from agentir_sdk.graph_proxy import GraphProxy
+
+workflow = StateGraph(MyState)
+G = GraphProxy(workflow)
+
+G.add_node("router", router)
+G.add_node("composer", composer)
+G.add_edge("router", "composer")
+
+G.set_entry_point("router")
+G.set_finish_point("composer")
+
+contract = G.build_contract()
+graph = G.materialize().compile()
+```
+
+### Other `GraphProxy` features
+
+- `attach_graph(node_name, subgraph)`: merge a subgraph view into the parent contract representation.
+- Entry-point RID guard insertion via `set_entry_point(...)` for per-run tracing context.
+- LLM handle detection and wrapping helpers to improve RID and node-name propagation.
+
+### RID and custom scheduler clients
+
+`agentir_sdk/rid.py` provides low-level helpers (`get_rid`, node-name context helpers, and wrappers) if you build custom LLM adapters.
+
+If you keep a user-owned scheduler client with its own `.invoke()` method, opt it into SDK header binding instead of reading `get_rid()` manually inside each node:
+
+```python
+from agentir_sdk.rid import SchedulerHeaderBindableMixin
+
+
+class SchedulerGateway(SchedulerHeaderBindableMixin):
+    def invoke(self, node_name: str, prompt: str) -> str:
+        headers = self.bound_scheduler_headers()
+        ...
+```
+
+`GraphProxy` can then wrap the client object in place, bind the scheduler RID and node name for each node call, and leave your node-level call sites alone.
+
+## Conditional routing annotation
+
+If you use `add_conditional_edges`, annotate route possibilities first:
+
+```python
+def route(state):
+    return "qa" if state.get("mode") == "qa" else "planner"
+
+G.annotate_conditional_edge("router", [["qa"], ["planner"]])
+G.add_conditional_edges("router", route, {
+    "qa": "qa",
+    "planner": "planner",
+})
+```
+
+**Why this matters**
+
+- It makes branch possibilities explicit in the generated contract.
+- It improves dependency visibility for schedulers and analyzers.
+
+If a conditional branch first passes through non-LLM nodes, `GraphProxy` will infer the first downstream LLM frontier for that branch automatically. When a branch merges with another branch before the first LLM node, that frontier is ambiguous; use `frontiers=` to pin it explicitly:
+
+```python
+G.annotate_conditional_edge(
+    "router",
+    [["non_llm_gateway"], ["direct_llm"]],
+    frontiers=[["writer", "critic"], ["direct_llm"]],
+)
+```
+
+## Contract shape
+
+`build_contract()` returns a `Contract` object with:
+
+- `entry`, `end`
+- `nodes[name].writes`
+- `nodes[name].llm_calls[]` with `model`, `reads`, `static_vars`
+- `edges[]` (`src`, `dst`, optional `label`)
+
+Serialize via:
+
+```python
+payload = contract.to_dict()
+```
+
+## High-level scheduling implications
+
+Without exposing internal policy details, annotations generally enable:
+
+- Better dependency tracking between nodes.
+- More accurate readiness analysis for downstream work.
+- Clearer branch and fanout structure for conditional paths.
+- Better observability of LLM call footprints.
+
+Poor or missing annotations usually mean less precise planning and fewer optimization opportunities.
+
+## Best practices
+
+- Keep `writes` minimal and accurate.
+- Keep `reads` specific to actual prompt inputs.
+- Use stable names for state keys and model IDs.
+- Annotate every node that performs LLM calls.
+- Annotate conditional structures before adding conditional edges.
+- Rebuild contracts after graph topology or annotation changes.
+
+## Common mistakes
+
+- Declaring `writes` keys that are never returned.
+- Omitting keys in `reads` that are used in prompt construction.
+- Forgetting to annotate conditional route options.
+- Treating `static_vars` as dynamic runtime data.
+
+## End-to-end example
+
+```python
+from typing import TypedDict
+from langchain_core.messages import AIMessage
+from langgraph.graph import StateGraph
+from agentir_sdk.decorators import writes, llm_call
+from agentir_sdk.graph_proxy import GraphProxy
+
+class DocState(TypedDict, total=False):
+    messages: list
+    route: str
+    draft: str
+
+@writes("route", "messages")
+@llm_call(model="router-model", reads=["messages"], static_vars=["route_prompt_v1"])
+def router(state: DocState, config=None):
+    user = state["messages"][-1].content
+    route = "qa" if "qa" in user.lower() else "write"
+    return {"route": route, "messages": [AIMessage(content=f"[route] {route}")]}
+
+@writes("draft", "messages")
+@llm_call(model="writer-model", reads=["messages"], static_vars=["writer_prompt_v2"])
+def writer(state: DocState, config=None):
+    return {"draft": "hello", "messages": [AIMessage(content="[writer] done")]}
+
+@writes("draft", "messages")
+@llm_call(model="qa-model", reads=["messages"], static_vars=["qa_prompt_v1"])
+def qa(state: DocState, config=None):
+    return {"draft": "answer", "messages": [AIMessage(content="[qa] done")]}
+
+wf = StateGraph(DocState)
+G = GraphProxy(wf)
+
+G.add_node("router", router)
+G.add_node("writer", writer)
+G.add_node("qa", qa)
+
+G.set_entry_point("router")
+
+G.annotate_conditional_edge("router", [["writer"], ["qa"]])
+G.add_conditional_edges("router", lambda s: "qa" if s.get("route") == "qa" else "writer", {
+    "writer": "writer",
+    "qa": "qa",
+})
+
+G.set_finish_point("writer")
+G.set_finish_point("qa")
+
+contract = G.build_contract()
+```
+
+## Important invariants
+
+- `@writes` and `@llm_call` annotations should reflect the real graph contract.
+- `GraphProxy.build_contract()` is the source of truth for scheduler-facing contract serialization.
+- RID propagation should remain explicit and observable; missing RID or node-name metadata is a correctness problem.

agentir_langgraph_annotation-0.1.0/pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agentir-langgraph-annotation"
+version = "0.1.0"
+description = "Public AgentIR SDK, decorators, contract tooling, and client logging helpers."
+license = "MIT"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["agentir_langgraph_annotation*"]

agentir_langgraph_annotation-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agentir_langgraph_annotation-0.1.0/src/agentir_langgraph_annotation.egg-info/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: agentir-langgraph-annotation
+Version: 0.1.0
+Summary: Public AgentIR SDK, decorators, contract tooling, and client logging helpers.
+License-Expression: MIT
+License-File: LICENSE
+Dynamic: license-file

agentir_langgraph_annotation-0.1.0/src/agentir_langgraph_annotation.egg-info/SOURCES.txt

@@ -0,0 +1,7 @@
+LICENSE
+README.md
+pyproject.toml
+src/agentir_langgraph_annotation.egg-info/PKG-INFO
+src/agentir_langgraph_annotation.egg-info/SOURCES.txt
+src/agentir_langgraph_annotation.egg-info/dependency_links.txt
+src/agentir_langgraph_annotation.egg-info/top_level.txt

agentir_langgraph_annotation-0.1.0/src/agentir_langgraph_annotation.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agentir_langgraph_annotation-0.1.0/src/agentir_langgraph_annotation.egg-info/top_level.txt

@@ -0,0 +1 @@
+