ctxgraph 0.2.0__tar.gz → 0.2.1__tar.gz

{ctxgraph-0.2.0 → ctxgraph-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxgraph
-Version: 0.2.0
+Version: 0.2.1
 Summary: AI context engine for Python — cuts LLM tokens 97% via code knowledge graphs. Build, query, and generate compact context capsules for Claude, OpenAI, Ollama.
 Author: ctxgraph contributors
 License: MIT
@@ -37,9 +37,11 @@ pip install ctxgraph
 ctx build                          # Build knowledge graph
 ctx capsule "fix JWT expiry"       # 92-99% fewer tokens vs raw code
 ccg "fix the login redirect bug"   # Launch Claude with context pre-loaded
-ctx view                           # Interactive D3.js visualization
+ctx view                           # Interactive D3.js visualization (or --svg for static)
 ```
 
+<img src="docs/graph.svg" alt="ctxgraph knowledge graph visualization" width="100%">
+
 ---
 
 ## Why ctxgraph?
@@ -248,7 +250,7 @@ ccg --mode deep "redesign the database schema"        # Deep mode
 exclude = ["legacy/*", "vendor/*"]
 
 [ai]
-provider = "ollama"           # ollama, claude, openai, custom
+provider = "ollama"           # ollama, claude, openai, azure, custom
 model = "qwen2.5-coder:7b"
 endpoint = "http://localhost:11434"
 
@@ -265,6 +267,7 @@ max_depth = 2
 | `CTXGRAPH_ENDPOINT` | `ai.endpoint` |
 | `ANTHROPIC_API_KEY` | Claude API |
 | `OPENAI_API_KEY` | OpenAI API |
+| `AZURE_OPENAI_API_KEY` | Azure OpenAI API |
 
 ```bash
 # Ollama (default)
@@ -276,6 +279,13 @@ CTXGRAPH_PROVIDER=claude CTXGRAPH_MODEL=claude-sonnet-4-20250514 ctx capsule "qu
 # OpenAI
 CTXGRAPH_PROVIDER=openai CTXGRAPH_MODEL=gpt-4o ctx capsule "query"
 
+# Azure OpenAI
+CTXGRAPH_PROVIDER=azure \
+  CTXGRAPH_MODEL=gpt-4o \
+  CTXGRAPH_ENDPOINT=https://my-resource.openai.azure.com \
+  AZURE_OPENAI_API_KEY=sk-... \
+  ctx capsule "query"
+
 # Custom (OpenAI-compatible)
 CTXGRAPH_PROVIDER=custom CTXGRAPH_ENDPOINT=http://my-api/v1 ctx capsule "query"
 ```
@@ -307,6 +317,185 @@ ctx capsule "extract payment processing into separate module" --mode deep
 
 ---
 
+## Framework Integrations
+
+ctxgraph can be used as a Python library — not just a CLI. This makes it easy to plug into LangChain, LangGraph, OpenAI Agents, or any custom AI pipeline.
+
+### Python API
+
+```python
+from pathlib import Path
+from ctxgraph.graph.builder import build_graph, get_storage
+from ctxgraph.capsule.renderer import render_capsule
+from ctxgraph.graph.query import search_relevant_nodes
+
+# 1. Build the graph (one-time setup)
+stats = build_graph(Path("/path/to/project"))
+print(f"Built: {stats['total_nodes']} nodes, {stats['total_edges']} edges")
+
+# 2. Get storage for an existing graph
+storage = get_storage(Path("/path/to/project"))
+
+# 3. Generate a context capsule (token-efficient text)
+capsule = render_capsule(storage, "fix JWT token validation", max_nodes=20)
+print(capsule)
+
+# 4. Search for relevant nodes programmatically
+results = search_relevant_nodes(storage, "auth login", max_nodes=10, max_depth=2)
+for node, score in results:
+    print(f"  {node.type}:{node.name}  (score={score})")
+```
+
+### LangChain
+
+Inject ctxgraph capsules directly into your LangChain prompts — dramatically reducing token usage while providing precise code context.
+
+```python
+from pathlib import Path
+from langchain_openai import ChatOpenAI
+from langchain_core.prompts import ChatPromptTemplate
+from ctxgraph.graph.builder import build_graph, get_storage
+from ctxgraph.capsule.renderer import render_capsule
+
+# Build graph once
+build_graph(Path("./my_project"))
+storage = get_storage(Path("./my_project"))
+
+# Generate context for a specific task
+context = render_capsule(storage, "user authentication flow", max_nodes=20)
+
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are a senior Python developer. Use the code context below to answer the question.\n\n{context}"),
+    ("user", "{question}"),
+])
+
+llm = ChatOpenAI(model="gpt-4o")
+chain = prompt | llm
+
+response = chain.invoke({
+    "context": context,
+    "question": "Where is the login rate limiter implemented?",
+})
+```
+
+### LangGraph
+
+Use ctxgraph as a tool within a LangGraph agent — the agent requests context capsules when it needs to understand the codebase.
+
+```python
+from pathlib import Path
+from typing import Literal
+from langgraph.graph import StateGraph, MessagesState
+from langgraph.prebuilt import ToolNode
+from langchain_openai import ChatOpenAI
+from langchain_core.tools import tool
+from ctxgraph.graph.builder import build_graph, get_storage
+from ctxgraph.capsule.renderer import render_capsule
+
+# Pre-build graph
+build_graph(Path("./my_project"))
+storage = get_storage(Path("./my_project"))
+
+@tool
+def code_context(task: str) -> str:
+    """Get code context relevant to a task. Use this before answering code questions."""
+    return render_capsule(storage, task, max_nodes=20)
+
+tools = [code_context]
+tool_node = ToolNode(tools)
+
+model = ChatOpenAI(model="gpt-4o", temperature=0).bind_tools(tools)
+
+def should_continue(state: MessagesState) -> Literal["tools", "__end__"]:
+    return "tools" if state["messages"][-1].tool_calls else "__end__"
+
+def call_model(state: MessagesState):
+    return {"messages": [model.invoke(state["messages"])]}
+
+graph = StateGraph(MessagesState)
+graph.add_node("agent", call_model)
+graph.add_node("tools", tool_node)
+graph.set_entry_point("agent")
+graph.add_conditional_edges("agent", should_continue)
+graph.add_edge("tools", "agent")
+
+app = graph.compile()
+
+for chunk in app.stream({"messages": [("user", "Find the bug in the payment processor")]}):
+    for node, msg in chunk.items():
+        print(f"[{node}]: {msg['messages'][0].content[:200] if msg.get('messages') else ''}")
+```
+
+### OpenAI Agents SDK
+
+Use ctxgraph with the official OpenAI Agents SDK (also works with Azure OpenAI via `AzureOpenAIChatCompletionAgent`).
+
+```python
+from pathlib import Path
+from openai import AzureOpenAI  # or OpenAI for standard API
+from agents import Agent, Runner, function_tool
+from ctxgraph.graph.builder import build_graph, get_storage
+from ctxgraph.capsule.renderer import render_capsule
+
+# Pre-build the graph
+build_graph(Path("./my_project"))
+storage = get_storage(Path("./my_project"))
+
+@function_tool
+def fetch_code_context(task_description: str) -> str:
+    """Retrieve relevant code context for a development task."""
+    return render_capsule(storage, task_description, max_nodes=20)
+
+agent = Agent(
+    name="Code Assistant",
+    instructions="You are a helpful coding assistant. Use the code context tool to understand the codebase before answering.",
+    model="gpt-4o",  # or AzureOpenAIChatCompletionAgent(deployment="gpt-4o", ...)
+    tools=[fetch_code_context],
+)
+
+result = Runner.run_sync(
+    agent,
+    "How does the JWT authentication middleware work?",
+)
+print(result.final_output)
+```
+
+### Azure OpenAI with Custom Agent
+
+For Azure OpenAI, configure the client directly and inject ctxgraph context:
+
+```python
+import os
+from openai import AzureOpenAI
+from pathlib import Path
+from ctxgraph.graph.builder import build_graph, get_storage
+from ctxgraph.capsule.renderer import render_capsule
+
+# Build graph
+build_graph(Path("./my_project"))
+storage = get_storage(Path("./my_project"))
+
+# Generate context capsule
+context = render_capsule(storage, "authentication and authorization", max_nodes=25)
+
+client = AzureOpenAI(
+    api_version="2024-08-01-preview",
+    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
+    api_key=os.environ["AZURE_OPENAI_API_KEY"],
+)
+
+response = client.chat.completions.create(
+    model="gpt-4o",  # deployment name
+    messages=[
+        {"role": "system", "content": f"You are a senior Python developer. Use the code context below.\n\n{context}"},
+        {"role": "user", "content": "Explain the role-based access control (RBAC) implementation."},
+    ],
+)
+print(response.choices[0].message.content)
+```
+
+---
+
 ## Development
 
 ```bash

{ctxgraph-0.2.0 → ctxgraph-0.2.1}/README.md

@@ -8,9 +8,11 @@ pip install ctxgraph
 ctx build                          # Build knowledge graph
 ctx capsule "fix JWT expiry"       # 92-99% fewer tokens vs raw code
 ccg "fix the login redirect bug"   # Launch Claude with context pre-loaded
-ctx view                           # Interactive D3.js visualization
+ctx view                           # Interactive D3.js visualization (or --svg for static)
 ```
 
+<img src="docs/graph.svg" alt="ctxgraph knowledge graph visualization" width="100%">
+
 ---
 
 ## Why ctxgraph?
@@ -219,7 +221,7 @@ ccg --mode deep "redesign the database schema"        # Deep mode
 exclude = ["legacy/*", "vendor/*"]
 
 [ai]
-provider = "ollama"           # ollama, claude, openai, custom
+provider = "ollama"           # ollama, claude, openai, azure, custom
 model = "qwen2.5-coder:7b"
 endpoint = "http://localhost:11434"
 
@@ -236,6 +238,7 @@ max_depth = 2
 | `CTXGRAPH_ENDPOINT` | `ai.endpoint` |
 | `ANTHROPIC_API_KEY` | Claude API |
 | `OPENAI_API_KEY` | OpenAI API |
+| `AZURE_OPENAI_API_KEY` | Azure OpenAI API |
 
 ```bash
 # Ollama (default)
@@ -247,6 +250,13 @@ CTXGRAPH_PROVIDER=claude CTXGRAPH_MODEL=claude-sonnet-4-20250514 ctx capsule "qu
 # OpenAI
 CTXGRAPH_PROVIDER=openai CTXGRAPH_MODEL=gpt-4o ctx capsule "query"
 
+# Azure OpenAI
+CTXGRAPH_PROVIDER=azure \
+  CTXGRAPH_MODEL=gpt-4o \
+  CTXGRAPH_ENDPOINT=https://my-resource.openai.azure.com \
+  AZURE_OPENAI_API_KEY=sk-... \
+  ctx capsule "query"
+
 # Custom (OpenAI-compatible)
 CTXGRAPH_PROVIDER=custom CTXGRAPH_ENDPOINT=http://my-api/v1 ctx capsule "query"
 ```
@@ -278,6 +288,185 @@ ctx capsule "extract payment processing into separate module" --mode deep
 
 ---
 
+## Framework Integrations
+
+ctxgraph can be used as a Python library — not just a CLI. This makes it easy to plug into LangChain, LangGraph, OpenAI Agents, or any custom AI pipeline.
+
+### Python API
+
+```python
+from pathlib import Path
+from ctxgraph.graph.builder import build_graph, get_storage
+from ctxgraph.capsule.renderer import render_capsule
+from ctxgraph.graph.query import search_relevant_nodes
+
+# 1. Build the graph (one-time setup)
+stats = build_graph(Path("/path/to/project"))
+print(f"Built: {stats['total_nodes']} nodes, {stats['total_edges']} edges")
+
+# 2. Get storage for an existing graph
+storage = get_storage(Path("/path/to/project"))
+
+# 3. Generate a context capsule (token-efficient text)
+capsule = render_capsule(storage, "fix JWT token validation", max_nodes=20)
+print(capsule)
+
+# 4. Search for relevant nodes programmatically
+results = search_relevant_nodes(storage, "auth login", max_nodes=10, max_depth=2)
+for node, score in results:
+    print(f"  {node.type}:{node.name}  (score={score})")
+```
+
+### LangChain
+
+Inject ctxgraph capsules directly into your LangChain prompts — dramatically reducing token usage while providing precise code context.
+
+```python
+from pathlib import Path
+from langchain_openai import ChatOpenAI
+from langchain_core.prompts import ChatPromptTemplate
+from ctxgraph.graph.builder import build_graph, get_storage
+from ctxgraph.capsule.renderer import render_capsule
+
+# Build graph once
+build_graph(Path("./my_project"))
+storage = get_storage(Path("./my_project"))
+
+# Generate context for a specific task
+context = render_capsule(storage, "user authentication flow", max_nodes=20)
+
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are a senior Python developer. Use the code context below to answer the question.\n\n{context}"),
+    ("user", "{question}"),
+])
+
+llm = ChatOpenAI(model="gpt-4o")
+chain = prompt | llm
+
+response = chain.invoke({
+    "context": context,
+    "question": "Where is the login rate limiter implemented?",
+})
+```
+
+### LangGraph
+
+Use ctxgraph as a tool within a LangGraph agent — the agent requests context capsules when it needs to understand the codebase.
+
+```python
+from pathlib import Path
+from typing import Literal
+from langgraph.graph import StateGraph, MessagesState
+from langgraph.prebuilt import ToolNode
+from langchain_openai import ChatOpenAI
+from langchain_core.tools import tool
+from ctxgraph.graph.builder import build_graph, get_storage
+from ctxgraph.capsule.renderer import render_capsule
+
+# Pre-build graph
+build_graph(Path("./my_project"))
+storage = get_storage(Path("./my_project"))
+
+@tool
+def code_context(task: str) -> str:
+    """Get code context relevant to a task. Use this before answering code questions."""
+    return render_capsule(storage, task, max_nodes=20)
+
+tools = [code_context]
+tool_node = ToolNode(tools)
+
+model = ChatOpenAI(model="gpt-4o", temperature=0).bind_tools(tools)
+
+def should_continue(state: MessagesState) -> Literal["tools", "__end__"]:
+    return "tools" if state["messages"][-1].tool_calls else "__end__"
+
+def call_model(state: MessagesState):
+    return {"messages": [model.invoke(state["messages"])]}
+
+graph = StateGraph(MessagesState)
+graph.add_node("agent", call_model)
+graph.add_node("tools", tool_node)
+graph.set_entry_point("agent")
+graph.add_conditional_edges("agent", should_continue)
+graph.add_edge("tools", "agent")
+
+app = graph.compile()
+
+for chunk in app.stream({"messages": [("user", "Find the bug in the payment processor")]}):
+    for node, msg in chunk.items():
+        print(f"[{node}]: {msg['messages'][0].content[:200] if msg.get('messages') else ''}")
+```
+
+### OpenAI Agents SDK
+
+Use ctxgraph with the official OpenAI Agents SDK (also works with Azure OpenAI via `AzureOpenAIChatCompletionAgent`).
+
+```python
+from pathlib import Path
+from openai import AzureOpenAI  # or OpenAI for standard API
+from agents import Agent, Runner, function_tool
+from ctxgraph.graph.builder import build_graph, get_storage
+from ctxgraph.capsule.renderer import render_capsule
+
+# Pre-build the graph
+build_graph(Path("./my_project"))
+storage = get_storage(Path("./my_project"))
+
+@function_tool
+def fetch_code_context(task_description: str) -> str:
+    """Retrieve relevant code context for a development task."""
+    return render_capsule(storage, task_description, max_nodes=20)
+
+agent = Agent(
+    name="Code Assistant",
+    instructions="You are a helpful coding assistant. Use the code context tool to understand the codebase before answering.",
+    model="gpt-4o",  # or AzureOpenAIChatCompletionAgent(deployment="gpt-4o", ...)
+    tools=[fetch_code_context],
+)
+
+result = Runner.run_sync(
+    agent,
+    "How does the JWT authentication middleware work?",
+)
+print(result.final_output)
+```
+
+### Azure OpenAI with Custom Agent
+
+For Azure OpenAI, configure the client directly and inject ctxgraph context:
+
+```python
+import os
+from openai import AzureOpenAI
+from pathlib import Path
+from ctxgraph.graph.builder import build_graph, get_storage
+from ctxgraph.capsule.renderer import render_capsule
+
+# Build graph
+build_graph(Path("./my_project"))
+storage = get_storage(Path("./my_project"))
+
+# Generate context capsule
+context = render_capsule(storage, "authentication and authorization", max_nodes=25)
+
+client = AzureOpenAI(
+    api_version="2024-08-01-preview",
+    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
+    api_key=os.environ["AZURE_OPENAI_API_KEY"],
+)
+
+response = client.chat.completions.create(
+    model="gpt-4o",  # deployment name
+    messages=[
+        {"role": "system", "content": f"You are a senior Python developer. Use the code context below.\n\n{context}"},
+        {"role": "user", "content": "Explain the role-based access control (RBAC) implementation."},
+    ],
+)
+print(response.choices[0].message.content)
+```
+
+---
+
 ## Development
 
 ```bash

{ctxgraph-0.2.0 → ctxgraph-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ctxgraph"
-version = "0.2.0"
+version = "0.2.1"
 description = "AI context engine for Python — cuts LLM tokens 97% via code knowledge graphs. Build, query, and generate compact context capsules for Claude, OpenAI, Ollama."
 readme = "README.md"
 license = {text = "MIT"}

{ctxgraph-0.2.0 → ctxgraph-0.2.1}/src/ctxgraph/cli/main.py

@@ -160,14 +160,17 @@ def view(
     ),
     port: Optional[int] = typer.Option(None, "--port", "-p", help="Port for server"),
     output: Optional[str] = typer.Option(
-        None, "--output", "-o", help="Save HTML to file"
+        None, "--output", "-o", help="Save HTML/SVG to file"
     ),
     open_browser: bool = typer.Option(
         True, "--open/--no-open", help="Open in browser automatically"
     ),
+    svg: bool = typer.Option(
+        False, "--svg", help="Generate static SVG instead of interactive HTML"
+    ),
 ):
     """Visualize the dependency graph in a browser."""
-    from ctxgraph.view.visualizer import render_view
+    from ctxgraph.view.visualizer import render_view, render_svg
 
     path = Path(repo_path).resolve() if repo_path else Path.cwd()
     storage = get_storage(path)
@@ -177,19 +180,25 @@ def view(
         )
         raise typer.Exit(1)
 
-    html = render_view(storage)
+    if svg:
+        content = render_svg(storage)
+        suffix = ".svg"
+    else:
+        content = render_view(storage)
+        suffix = ".html"
 
     if output:
         out_path = Path(output)
-        out_path.write_text(html, encoding="utf-8")
+        out_path.write_text(content, encoding="utf-8")
         console.print(f"Saved to [bold]{out_path}[/bold]")
     else:
-        out_path = path / ".ctxgraph" / "graph.html"
+        filename = f"graph{suffix}"
+        out_path = path / ".ctxgraph" / filename
         out_path.parent.mkdir(parents=True, exist_ok=True)
-        out_path.write_text(html, encoding="utf-8")
+        out_path.write_text(content, encoding="utf-8")
         console.print(f"Saved to [bold]{out_path}[/bold]")
 
-    if open_browser:
+    if open_browser and not svg:
         import webbrowser
 
         webbrowser.open(f"file://{out_path.absolute()}")

{ctxgraph-0.2.0 → ctxgraph-0.2.1}/src/ctxgraph/config/providers.py

@@ -21,6 +21,8 @@ def chat_completion(
         return _claude_chat(settings, system_prompt, user_prompt)
     elif provider == "openai":
         return _openai_chat(settings, system_prompt, user_prompt)
+    elif provider == "azure":
+        return _azure_chat(settings, system_prompt, user_prompt)
     else:
         return _custom_chat(settings, system_prompt, user_prompt)
 
@@ -125,6 +127,38 @@ def _openai_chat(settings: Settings, system: str, user: str) -> Optional[str]:
         return None
 
 
+def _azure_chat(settings: Settings, system: str, user: str) -> Optional[str]:
+    api_key = settings.api_key
+    if not api_key:
+        return None
+
+    url = settings.get_chat_url()
+    payload = {
+        "messages": [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ],
+        "max_tokens": settings.max_tokens,
+        "temperature": settings.temperature,
+    }
+
+    try:
+        data = json.dumps(payload).encode()
+        req = urllib.request.Request(
+            url,
+            data=data,
+            headers={
+                "Content-Type": "application/json",
+                "api-key": api_key,
+            },
+        )
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            result = json.loads(resp.read())
+            return result.get("choices", [{}])[0].get("message", {}).get("content", "")
+    except (urllib.error.URLError, json.JSONDecodeError, TimeoutError):
+        return None
+
+
 def _custom_chat(settings: Settings, system: str, user: str) -> Optional[str]:
     url = settings.get_chat_url()
     payload = {

{ctxgraph-0.2.0 → ctxgraph-0.2.1}/src/ctxgraph/config/settings.py

@@ -50,6 +50,14 @@ PROVIDER_CONFIGS = {
         "chat_endpoint": "/chat/completions",
         "api_key_env": "OPENAI_API_KEY",
     },
+    "azure": {
+        "endpoint_default": "https://YOUR_RESOURCE.openai.azure.com",
+        "api_key_required": True,
+        "models": ["gpt-4o", "gpt-4o-mini"],
+        "chat_endpoint": "/openai/deployments/{deployment}/chat/completions?api-version=2024-08-01-preview",
+        "api_key_env": "AZURE_OPENAI_API_KEY",
+        "api_key_header": "api-key",
+    },
     "custom": {
         "endpoint_default": None,
         "api_key_required": False,
@@ -158,7 +166,10 @@ class Settings:
     def get_chat_url(self) -> str:
         pconfig = self.get_provider_config()
         endpoint = self.endpoint.rstrip("/")
-        return f"{endpoint}{pconfig.get('chat_endpoint', '/v1/chat/completions')}"
+        chat_ep = pconfig.get("chat_endpoint", "/v1/chat/completions")
+        if "{deployment}" in chat_ep:
+            chat_ep = chat_ep.replace("{deployment}", self.model)
+        return f"{endpoint}{chat_ep}"
 
     def to_dict(self) -> dict:
         return dict(self._data)
@@ -210,7 +221,7 @@ def create_default_config(repo_path: Path):
 exclude = []
 
 [ai]
-# Provider: ollama, claude, openai, or custom
+# Provider: ollama, claude, openai, azure, or custom
 provider = "ollama"
 # Model name
 model = "qwen2.5-coder:7b"

{ctxgraph-0.2.0 → ctxgraph-0.2.1}/src/ctxgraph/view/visualizer.py

@@ -1,10 +1,27 @@
 from __future__ import annotations
 
 import json
+import math
 from pathlib import Path
 
 from ctxgraph.graph.storage import Storage
 
+# SVG constants
+SVG_WIDTH = 960
+SVG_HEIGHT = 680
+SVG_CENTER_X = SVG_WIDTH // 2
+SVG_CENTER_Y = SVG_HEIGHT // 2
+SVG_RADIUS = 260
+
+COLORS = {
+    "file": "#58a6ff",
+    "class": "#d29922",
+    "function": "#3fb950",
+    "module": "#bc8cff",
+}
+
+NODE_ORDER = {"file": 0, "class": 1, "function": 2, "module": 3}
+
 
 def render_view(storage: Storage) -> str:
     nodes = storage.get_all_nodes()
@@ -62,6 +79,103 @@ def render_view(storage: Storage) -> str:
     return template.replace("/* GRAPH_DATA */", json_data)
 
 
+def render_svg(storage: Storage) -> str:
+    """Generate a static SVG visualization of the knowledge graph."""
+    nodes = storage.get_all_nodes()
+    edges = storage.get_all_edges()
+
+    file_nodes = [n for n in nodes if n.type == "file"]
+    symbol_nodes = [n for n in nodes if n.type != "file"]
+    file_node_ids = {n.id for n in file_nodes}
+
+    # Layout: files in a circle, symbols at parent file position
+    n_files = len(file_nodes)
+    positions: dict[str, tuple[float, float]] = {}
+
+    for i, node in enumerate(file_nodes):
+        angle = (2 * math.pi * i / n_files) - math.pi / 2
+        x = SVG_CENTER_X + SVG_RADIUS * math.cos(angle)
+        y = SVG_CENTER_Y + SVG_RADIUS * math.sin(angle)
+        positions[node.id] = (x, y)
+
+    # Place symbol nodes near their parent file (offset slightly)
+    for node in symbol_nodes:
+        parent_id = f"file:{node.path}" if node.path else None
+        if parent_id and parent_id in positions:
+            px, py = positions[parent_id]
+            offset = 22
+            positions[node.id] = (px + offset, py + offset)
+        else:
+            positions[node.id] = (SVG_CENTER_X, SVG_CENTER_Y)
+
+    # Build edge lines
+    edge_lines: list[str] = []
+    for edge in edges:
+        src = positions.get(edge.source_id)
+        tgt = positions.get(edge.target_id)
+        if src and tgt:
+            edge_lines.append(
+                f'<line x1="{src[0]:.1f}" y1="{src[1]:.1f}" '
+                f'x2="{tgt[0]:.1f}" y2="{tgt[1]:.1f}" '
+                f'class="edge edge-{edge.relation}" />'
+            )
+
+    # Build node circles + labels
+    all_nodes = file_nodes + symbol_nodes
+    all_nodes.sort(key=lambda n: NODE_ORDER.get(n.type, 9))
+
+    node_groups: list[str] = []
+    for node in all_nodes:
+        x, y = positions.get(node.id, (SVG_CENTER_X, SVG_CENTER_Y))
+        r = 5 + (node.importance or 0.5) * 5
+        color = COLORS.get(node.type, "#8b949e")
+        label = node.name
+        node_groups.append(
+            f'<g class="node node-{node.type}">'
+            f'<circle cx="{x:.1f}" cy="{y:.1f}" r="{r:.1f}" fill="{color}" stroke="#161b22" stroke-width="1.5" />'
+            f'<text x="{x + r + 6:.1f}" y="{y + 4:.1f}" class="label">{_esc(label)}</text>'
+            f'</g>'
+        )
+
+    # Stats
+    n_edges = len(set((e.source_id, e.target_id) for e in edges))
+
+    return f"""<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {SVG_WIDTH} {SVG_HEIGHT}" width="100%" height="100%" style="font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:#0d1117;color:#c9d1d9;">
+<style>
+  .edge {{ stroke-opacity:0.4; stroke-width:1.2; }}
+  .edge-imports {{ stroke:#58a6ff; stroke-dasharray:4,2; }}
+  .edge-calls {{ stroke:#3fb950; stroke-dasharray:2,2; }}
+  .edge-defines {{ stroke:#d29922; }}
+  .edge-extends {{ stroke:#bc8cff; }}
+  .node {{ cursor:pointer; }}
+  .node-file circle {{ filter: drop-shadow(0 0 4px #58a6ff55); }}
+  .label {{ fill:#8b949e; font-size:10px; }}
+  .node-file .label {{ fill:#c9d1d9; font-weight:600; }}
+  .title {{ fill:#c9d1d9; font-size:18px; font-weight:700; }}
+  .subtitle {{ fill:#8b949e; font-size:12px; }}
+  .legend-item text {{ fill:#8b949e; font-size:11px; }}
+</style>
+<rect width="100%" height="100%" fill="#0d1117" />
+<text x="20" y="30" class="title">ctxgraph — Knowledge Graph</text>
+<text x="20" y="48" class="subtitle">{len(nodes)} nodes, {n_edges} edges</text>
+<g id="edges">{''.join(edge_lines)}</g>
+<g id="nodes">{''.join(node_groups)}</g>
+<g id="legend" transform="translate(20, {SVG_HEIGHT - 100})">
+  <rect x="0" y="0" width="220" height="80" rx="6" fill="#161b22" stroke="#30363d" stroke-width="1" />
+  <circle cx="16" cy="18" r="5" fill="#58a6ff" /><text x="28" y="22" class="legend-item">File</text>
+  <circle cx="16" cy="38" r="5" fill="#d29922" /><text x="28" y="42" class="legend-item">Class</text>
+  <circle cx="16" cy="58" r="5" fill="#3fb950" /><text x="28" y="62" class="legend-item">Function</text>
+  <line x1="110" y1="16" x2="140" y2="16" stroke="#58a6ff" stroke-dasharray="4,2" stroke-width="1.5"/><text x="146" y="20" class="legend-item">Import</text>
+  <line x1="110" y1="36" x2="140" y2="36" stroke="#3fb950" stroke-dasharray="2,2" stroke-width="1.5"/><text x="146" y="40" class="legend-item">Call</text>
+  <line x1="110" y1="56" x2="140" y2="56" stroke="#d29922" stroke-width="1.5"/><text x="146" y="60" class="legend-item">Defines</text>
+</g>
+</svg>"""
+
+
+def _esc(text: str) -> str:
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;").replace('"', "&quot;")
+
+
 def _short_path(path: str) -> str:
     parts = path.split("/")
     if len(parts) > 3:

{ctxgraph-0.2.0 → ctxgraph-0.2.1}/src/ctxgraph.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxgraph
-Version: 0.2.0
+Version: 0.2.1
 Summary: AI context engine for Python — cuts LLM tokens 97% via code knowledge graphs. Build, query, and generate compact context capsules for Claude, OpenAI, Ollama.
 Author: ctxgraph contributors
 License: MIT
@@ -37,9 +37,11 @@ pip install ctxgraph
 ctx build                          # Build knowledge graph
 ctx capsule "fix JWT expiry"       # 92-99% fewer tokens vs raw code
 ccg "fix the login redirect bug"   # Launch Claude with context pre-loaded
-ctx view                           # Interactive D3.js visualization
+ctx view                           # Interactive D3.js visualization (or --svg for static)
 ```
 
+<img src="docs/graph.svg" alt="ctxgraph knowledge graph visualization" width="100%">
+
 ---
 
 ## Why ctxgraph?
@@ -248,7 +250,7 @@ ccg --mode deep "redesign the database schema"        # Deep mode
 exclude = ["legacy/*", "vendor/*"]
 
 [ai]
-provider = "ollama"           # ollama, claude, openai, custom
+provider = "ollama"           # ollama, claude, openai, azure, custom
 model = "qwen2.5-coder:7b"
 endpoint = "http://localhost:11434"
 
@@ -265,6 +267,7 @@ max_depth = 2
 | `CTXGRAPH_ENDPOINT` | `ai.endpoint` |
 | `ANTHROPIC_API_KEY` | Claude API |
 | `OPENAI_API_KEY` | OpenAI API |
+| `AZURE_OPENAI_API_KEY` | Azure OpenAI API |
 
 ```bash
 # Ollama (default)
@@ -276,6 +279,13 @@ CTXGRAPH_PROVIDER=claude CTXGRAPH_MODEL=claude-sonnet-4-20250514 ctx capsule "qu
 # OpenAI
 CTXGRAPH_PROVIDER=openai CTXGRAPH_MODEL=gpt-4o ctx capsule "query"
 
+# Azure OpenAI
+CTXGRAPH_PROVIDER=azure \
+  CTXGRAPH_MODEL=gpt-4o \
+  CTXGRAPH_ENDPOINT=https://my-resource.openai.azure.com \
+  AZURE_OPENAI_API_KEY=sk-... \
+  ctx capsule "query"
+
 # Custom (OpenAI-compatible)
 CTXGRAPH_PROVIDER=custom CTXGRAPH_ENDPOINT=http://my-api/v1 ctx capsule "query"
 ```
@@ -307,6 +317,185 @@ ctx capsule "extract payment processing into separate module" --mode deep
 
 ---
 
+## Framework Integrations
+
+ctxgraph can be used as a Python library — not just a CLI. This makes it easy to plug into LangChain, LangGraph, OpenAI Agents, or any custom AI pipeline.
+
+### Python API
+
+```python
+from pathlib import Path
+from ctxgraph.graph.builder import build_graph, get_storage
+from ctxgraph.capsule.renderer import render_capsule
+from ctxgraph.graph.query import search_relevant_nodes
+
+# 1. Build the graph (one-time setup)
+stats = build_graph(Path("/path/to/project"))
+print(f"Built: {stats['total_nodes']} nodes, {stats['total_edges']} edges")
+
+# 2. Get storage for an existing graph
+storage = get_storage(Path("/path/to/project"))
+
+# 3. Generate a context capsule (token-efficient text)
+capsule = render_capsule(storage, "fix JWT token validation", max_nodes=20)
+print(capsule)
+
+# 4. Search for relevant nodes programmatically
+results = search_relevant_nodes(storage, "auth login", max_nodes=10, max_depth=2)
+for node, score in results:
+    print(f"  {node.type}:{node.name}  (score={score})")
+```
+
+### LangChain
+
+Inject ctxgraph capsules directly into your LangChain prompts — dramatically reducing token usage while providing precise code context.
+
+```python
+from pathlib import Path
+from langchain_openai import ChatOpenAI
+from langchain_core.prompts import ChatPromptTemplate
+from ctxgraph.graph.builder import build_graph, get_storage
+from ctxgraph.capsule.renderer import render_capsule
+
+# Build graph once
+build_graph(Path("./my_project"))
+storage = get_storage(Path("./my_project"))
+
+# Generate context for a specific task
+context = render_capsule(storage, "user authentication flow", max_nodes=20)
+
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are a senior Python developer. Use the code context below to answer the question.\n\n{context}"),
+    ("user", "{question}"),
+])
+
+llm = ChatOpenAI(model="gpt-4o")
+chain = prompt | llm
+
+response = chain.invoke({
+    "context": context,
+    "question": "Where is the login rate limiter implemented?",
+})
+```
+
+### LangGraph
+
+Use ctxgraph as a tool within a LangGraph agent — the agent requests context capsules when it needs to understand the codebase.
+
+```python
+from pathlib import Path
+from typing import Literal
+from langgraph.graph import StateGraph, MessagesState
+from langgraph.prebuilt import ToolNode
+from langchain_openai import ChatOpenAI
+from langchain_core.tools import tool
+from ctxgraph.graph.builder import build_graph, get_storage
+from ctxgraph.capsule.renderer import render_capsule
+
+# Pre-build graph
+build_graph(Path("./my_project"))
+storage = get_storage(Path("./my_project"))
+
+@tool
+def code_context(task: str) -> str:
+    """Get code context relevant to a task. Use this before answering code questions."""
+    return render_capsule(storage, task, max_nodes=20)
+
+tools = [code_context]
+tool_node = ToolNode(tools)
+
+model = ChatOpenAI(model="gpt-4o", temperature=0).bind_tools(tools)
+
+def should_continue(state: MessagesState) -> Literal["tools", "__end__"]:
+    return "tools" if state["messages"][-1].tool_calls else "__end__"
+
+def call_model(state: MessagesState):
+    return {"messages": [model.invoke(state["messages"])]}
+
+graph = StateGraph(MessagesState)
+graph.add_node("agent", call_model)
+graph.add_node("tools", tool_node)
+graph.set_entry_point("agent")
+graph.add_conditional_edges("agent", should_continue)
+graph.add_edge("tools", "agent")
+
+app = graph.compile()
+
+for chunk in app.stream({"messages": [("user", "Find the bug in the payment processor")]}):
+    for node, msg in chunk.items():
+        print(f"[{node}]: {msg['messages'][0].content[:200] if msg.get('messages') else ''}")
+```
+
+### OpenAI Agents SDK
+
+Use ctxgraph with the official OpenAI Agents SDK (also works with Azure OpenAI via `AzureOpenAIChatCompletionAgent`).
+
+```python
+from pathlib import Path
+from openai import AzureOpenAI  # or OpenAI for standard API
+from agents import Agent, Runner, function_tool
+from ctxgraph.graph.builder import build_graph, get_storage
+from ctxgraph.capsule.renderer import render_capsule
+
+# Pre-build the graph
+build_graph(Path("./my_project"))
+storage = get_storage(Path("./my_project"))
+
+@function_tool
+def fetch_code_context(task_description: str) -> str:
+    """Retrieve relevant code context for a development task."""
+    return render_capsule(storage, task_description, max_nodes=20)
+
+agent = Agent(
+    name="Code Assistant",
+    instructions="You are a helpful coding assistant. Use the code context tool to understand the codebase before answering.",
+    model="gpt-4o",  # or AzureOpenAIChatCompletionAgent(deployment="gpt-4o", ...)
+    tools=[fetch_code_context],
+)
+
+result = Runner.run_sync(
+    agent,
+    "How does the JWT authentication middleware work?",
+)
+print(result.final_output)
+```
+
+### Azure OpenAI with Custom Agent
+
+For Azure OpenAI, configure the client directly and inject ctxgraph context:
+
+```python
+import os
+from openai import AzureOpenAI
+from pathlib import Path
+from ctxgraph.graph.builder import build_graph, get_storage
+from ctxgraph.capsule.renderer import render_capsule
+
+# Build graph
+build_graph(Path("./my_project"))
+storage = get_storage(Path("./my_project"))
+
+# Generate context capsule
+context = render_capsule(storage, "authentication and authorization", max_nodes=25)
+
+client = AzureOpenAI(
+    api_version="2024-08-01-preview",
+    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
+    api_key=os.environ["AZURE_OPENAI_API_KEY"],
+)
+
+response = client.chat.completions.create(
+    model="gpt-4o",  # deployment name
+    messages=[
+        {"role": "system", "content": f"You are a senior Python developer. Use the code context below.\n\n{context}"},
+        {"role": "user", "content": "Explain the role-based access control (RBAC) implementation."},
+    ],
+)
+print(response.choices[0].message.content)
+```
+
+---
+
 ## Development
 
 ```bash