Metadata-Version: 2.4
Name: langgraph-init-cli
Version: 0.1.3
Summary: CLI scaffolder for LangGraph projects
Author: Varsha
License-Expression: MIT
Project-URL: Homepage, https://github.com/varshasathya/langgraph-init-project
Project-URL: Repository, https://github.com/varshasathya/langgraph-init-project
Keywords: langgraph,langchain,cli,scaffolding,agent,python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langgraph>=0.2.0
Requires-Dist: langchain>=0.3.0
Requires-Dist: langsmith>=0.1.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: typer>=0.12.0
Dynamic: license-file

# langgraph-init-cli

A production-oriented scaffolding CLI for [LangGraph](https://github.com/langchain-ai/langgraph) projects. Generate opinionated project layouts that start simple and scale into a full agentic architecture — with graph orchestration, prompt versioning, tool registries, evaluation, observability, and LangSmith-ready tracing.

```bash
pip install langgraph-init-cli
langgraph-init my-app --template production
```

---

## Why langgraph-init?

Starting a LangGraph project from scratch means a lot of boilerplate: wiring state graphs, organizing nodes, managing prompts, hooking up LangSmith. `langgraph-init` gives you a well-structured starting point so you can skip the scaffolding and focus on the agent logic that matters.

---

## Installation

```bash
pip install langgraph-init-cli
```

Or for a cleaner global CLI experience:

```bash
pipx install langgraph-init-cli
```

---

## Usage

```bash
langgraph-init <project-name> --template <template>
```

**Available templates:**

| Template | Best For |
|---|---|
| `base` | Quick experiments and prototypes |
| `advanced` | Modular team projects with clean graph structure |
| `production` | Full production systems with tooling, observability, and evaluation |

**Example:**

```bash
langgraph-init my-app --template production
cd my-app
pip install -e .
python -m src.app.main
```

---

## Templates

### `base`

A minimal LangGraph starter to get something running fast.

- Small `StateGraph` with typed state
- A few nodes wired together
- Runnable via `src.app.main:run`

### `advanced`

A modular architecture for teams that want clean structure without full production overhead.

- `graph/` package with `builder.py`, `state.py`, `edges.py`, `constants.py`, `registry.py`
- `Names` / `Nodes` / `Tags` pattern for readable graph wiring
- `nodes/`, `services/`, `prompts/`, and `utils/` directories
- Prompt loading abstraction and conditional edges

### `production`

A complete scaffold intended for real systems. Everything is modular, runnable without external services, and ready to extend.

- Graph orchestration with `StateGraph`, conditional routing, and retry logic
- `RunnableParallel` example for parallel enrichment
- Prompt versioning system (`prompts/versions/<task>/v1.txt`, `v2.txt`, ...)
- Tool framework with `BaseTool`, registry, and example tools (calculator, retriever, HTTP-style)
- Evaluation, confidence scoring, and field coverage checks
- Structured JSON logging, metrics counters, trace decorators
- LangSmith integration (environment-driven, safe when disabled)
- Optional API entry surface and storage layer abstractions

**Generated layout:**

```
src/app/
├── main.py
├── config.py
├── graph/
├── nodes/
├── services/
├── tools/
├── prompts/
├── models/
├── storage/
├── utils/
├── observability/
├── evaluation/
└── api/
```

---

## Understanding the Generated Files

Here's what each file and folder does, and where to make changes when building your own agent.

### `config.py` — App Settings

Centralizes all configuration in a single `Settings` dataclass. Every value reads from environment variables with sensible defaults, so you control behavior via a `.env` file without touching code.

```python
# What's inside:
project_name       # Your app name
environment        # "development" | "production" (from APP_ENV)
log_level          # "INFO" by default (from LOG_LEVEL)
langsmith_tracing  # Toggle LangSmith tracing on/off (from LANGSMITH_TRACING)
langsmith_api_key  # Your LangSmith API key (from LANGSMITH_API_KEY)
default_prompt_versions  # e.g. {"intent": "v2", "extraction": "v1"}
max_validation_retries   # How many times to retry failed validation (default: 2)
```

**What to change here:** your project name, default prompt versions, and retry limits. Add any new env-driven settings your agent needs.

---

### `main.py` — Entrypoint

Builds the graph, creates a sample input state, runs it with `app.invoke()`, and prints the output. This is what executes when you run `python -m src.app.main`.

```python
def run():
    app = build_graph()
    sample_state = {
        "input_text": "Please calculate 12 + 7 and validate the answer.",
        "retry_count": 0,
        "messages": [],
        "prompt_versions": settings.default_prompt_versions.copy(),
        "tool_results": {},
    }
    result = app.invoke(sample_state)
    print(result.get("output", "No output produced."))
```

**What to change here:** replace `sample_state` with your real input schema. Swap the `input_text` for whatever your agent actually receives (a user message, a document, an API payload, etc.).

---

### `graph/` — Graph Orchestration

Owns the entire workflow definition. The key files are:

| File | Purpose |
|---|---|
| `builder.py` | Wires nodes and edges together into a `StateGraph` — start here to understand the flow |
| `state.py` | Defines the typed state that flows between nodes |
| `edges.py` | Conditional routing logic (e.g. retry vs continue vs error) |
| `constants.py` | `Names`, `Nodes`, and `Tags` classes for stable identifiers |
| `registry.py` | Maps node names to their callable implementations |

**What to change here:** add new nodes in `registry.py`, define new routes in `edges.py`, and expand the state schema in `state.py`.

---

### `nodes/` — Node Implementations

Each file handles one step in the workflow:

| File | What it does |
|---|---|
| `intent.py` | Classifies the incoming input |
| `processing.py` | Runs extraction and tool-backed enrichment |
| `validation.py` | Scores output quality and decides whether to retry |
| `output.py` | Builds and persists the final result |
| `error.py` | Produces a structured failure response |

**What to change here:** this is where most of your agent logic lives. Replace the stub implementations with real LLM calls, business logic, or tool invocations.

---

### `services/` — Reusable Logic

Holds logic that multiple nodes share, so it doesn't get duplicated:

| File | What it does |
|---|---|
| `llm_service.py` | LLM orchestration and parallel enrichment via `RunnableParallel` |
| `prompt_service.py` | Loads prompts by task/version with fallback to `v1` |
| `evaluation_service.py` | Coordinates evaluation scoring |
| `versioning_service.py` | Switches prompt versions at runtime |
| `tool_service.py` | Dispatches tool calls from the registry |

**What to change here:** swap the stub LLM calls in `llm_service.py` with your actual provider client (OpenAI, Anthropic, Gemini, etc.).

---

### `tools/` — Tool Framework

A small but extensible tool system with a `BaseTool` contract and registry. Comes with demo tools (calculator, retriever, HTTP-style query) you can run immediately and replace later.

**What to change here:** add your own tools by implementing `BaseTool` and registering them. Delete the demo tools when you no longer need them.

---

### `prompts/` — Prompt Versioning

Prompts are plain `.txt` files organized by task and version:

```
prompts/versions/
├── intent/
│   ├── v1.txt
│   └── v2.txt
├── extraction/
│   └── v1.txt
└── validation/
    └── v1.txt
```

The prompt service loads the version specified in `config.py` and falls back to `v1` if a version doesn't exist. This lets you iterate on prompts without changing code — just add a new version file and update the config.

**What to change here:** edit the `.txt` files directly. Add new task folders as your agent gains new capabilities.

---

### `observability/` — Logging and Metrics

Structured JSON logging and metrics counters out of the box. Trace decorators make it easy to instrument any function for LangSmith.

**What to change here:** add custom metrics or extend the trace decorators for new nodes.

---

### `evaluation/` — Output Scoring

Field coverage evaluation and confidence scoring to measure output quality during development. Feeds into the validation node's retry decision.

**What to change here:** expand the scoring rubric to match your domain's definition of a good output.

---

### `storage/` — Persistence Layer

Abstract storage interfaces with stub implementations. Designed to be swapped for a real database (Postgres, Redis, S3, etc.) without changing node code.

**What to change here:** implement the storage interface for your target database when you're ready to persist results.

---

### `api/` — Optional API Surface

A thin API layer (FastAPI-ready) you can enable if you want to expose the agent as an HTTP service.

**What to change here:** add your routes and request/response models here when you're ready to serve the agent over HTTP.

---

## Graph Wiring Pattern

The `advanced` and `production` templates use a three-concept pattern to keep graph wiring readable and maintainable:

```python
class Names:
    INTENT = "intent"       # Stable node identifiers

class Nodes:
    INTENT = intent_node    # Callable implementations

class Tags:
    CONTINUE = "continue"   # Routing labels for conditional edges
```

This separates string identifiers from executable functions, making edges easy to read and refactor.

---

## After Generation

Recommended next steps once you have your scaffold:

- Replace deterministic LLM stubs with your actual provider client
- Add real persistence in `storage/`
- Swap demo tools for domain-specific tools
- Expand evaluation metrics for your use case
- Add tests around graph routing and node behavior
- Set `LANGCHAIN_API_KEY` and related env vars to activate LangSmith tracing

---

## Generated `langgraph.json`

All projects include:

```json
{
  "dependencies": ["."],
  "graphs": {
    "<project-name>": "src.app.main:run"
  }
}
```

This keeps the entrypoint consistent and compatible with LangGraph tooling.

---

## Links

- **PyPI:** https://pypi.org/project/langgraph-init-cli/
- **LangGraph docs:** https://langchain-ai.github.io/langgraph/
- **LangSmith:** https://smith.langchain.com/

---

## License

MIT
