Metadata-Version: 2.4
Name: langgraph-init-cli
Version: 0.1.1
Summary: CLI scaffolder for LangGraph projects
Author: Varsha
License-Expression: MIT
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

`langgraph-init` is a production-oriented scaffolding CLI for LangGraph projects. It generates opinionated project layouts that start simple and scale into a modular agentic architecture with graph orchestration, prompts, tools, evaluation, observability, and LangSmith-ready tracing.

## What It Generates

The CLI ships with three templates:

### `base`

A minimal LangGraph starter intended for quick experiments.

Included:

- Small `StateGraph`
- Simple typed state
- A few nodes
- Minimal project structure
- Runnable `src.app.main:run`

### `advanced`

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

Included:

- `graph/` package with `builder.py`, `state.py`, `edges.py`, `constants.py`, `registry.py`
- Node registry and `Names` / `Nodes` / `Tags` pattern
- `nodes/`, `services/`, `prompts/`, and `utils/`
- Prompt loading abstraction
- Conditional edges

### `production`

A complete production-grade scaffold with architecture intended to be extended in real systems.

Included:

- Graph orchestration with `StateGraph`
- Conditional routing and retry logic
- `RunnableParallel` example
- Modular nodes and services
- Prompt versioning system
- Tool framework and registry
- Evaluation and scoring
- Structured logging
- LangSmith integration hooks
- Metrics and tracing utilities
- Storage layer abstractions
- Optional API entry surface

## Installation

From this repository:

```bash
pip install -e .
```

This installs the CLI command:

```bash
langgraph-init
```

## Usage

Create a project:

```bash
langgraph-init my-app --template production
```

Available templates:

- `base`
- `advanced`
- `production`

After generation:

```bash
cd my-app
python -m src.app.main
```

## Example Workflow

Typical flow for a production scaffold:

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

## CLI Design

The CLI is intentionally small:

- `langgraph_cli/cli.py` exposes the Typer command
- `langgraph_cli/generator.py` copies template files
- `{{PROJECT_NAME}}` placeholders are replaced during generation
- Embedded templates live under `langgraph_cli/templates/`

The generator also ignores Python cache artifacts so packaged templates remain clean when the CLI itself is compiled locally.

## Generated Project Conventions

The advanced and production templates use a graph abstraction pattern built around three concepts:

- `Names`: stable graph node identifiers used when wiring edges
- `Nodes`: callable node implementations
- `Tags`: routing labels for conditional edges

This pattern keeps graph wiring readable and separates string identifiers from executable node functions.

Example:

```python
class Names:
    INTENT = "intent"


class Nodes:
    INTENT = intent_node


class Tags:
    CONTINUE = "continue"
```

## Production Template Architecture

The production scaffold generates this high-level layout:

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

### Graph Layer

The graph layer is responsible for:

- Declaring typed workflow state
- Registering nodes
- Routing execution
- Handling validation retries
- Defining the orchestration contract

### Nodes

Each node handles one concern:

- `intent.py`: classify incoming intent
- `processing.py`: perform extraction and tool-backed enrichment
- `validation.py`: score output quality
- `output.py`: build and persist the final workflow result
- `error.py`: produce a final failure response

### Services

Services hold reusable logic that should not live inside nodes:

- `llm_service.py`: deterministic LLM-style orchestration and parallel enrichment
- `prompt_service.py`: prompt loading and access tracking
- `evaluation_service.py`: evaluation coordination
- `versioning_service.py`: prompt version switching
- `tool_service.py`: tool dispatch

### Tools

The production template includes a small but extensible tool framework:

- `BaseTool` contract
- Tool registry
- Deterministic query tool
- Deterministic HTTP-style tool
- Calculator tool
- Retriever tool

### Prompt Versioning

Prompts are stored by task and version:

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

The prompt service:

- Loads prompts by task/version
- Falls back to default configured versions
- Falls back to `v1` if a requested version does not exist
- Records prompt access through a store abstraction

### Evaluation and Observability

The production scaffold includes:

- Field coverage evaluation
- Confidence scoring
- Structured JSON logging
- Metrics counters
- LangSmith environment configuration
- Trace decorators

## langgraph.json

Generated projects include:

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

This keeps the project aligned with the requested `src.app.main:run` entrypoint.

## Extending the Scaffold

Recommended next steps after generation:

- Replace deterministic LLM stubs with your provider client
- Add real persistence in `storage/`
- Replace demo tools with domain tools
- Expand evaluation metrics
- Add tests around graph routing and node behavior
- Introduce environment-specific config loading

## Notes

- The generated code is runnable without external services by design
- LangSmith integration is environment-driven and safe by default when disabled
- The production template favors clean architecture over tight coupling

## Release Guide

This package can be published so others can install it with `pip` or `pipx` without cloning the repository.

### Before You Publish

Review these items first:

- Update the version in `pyproject.toml`
- Make sure the package name is the one you want to publish
- Confirm the dependency list is still minimal and intentional
- Add repository URLs to `pyproject.toml` later if you want PyPI to link to your source repo

Current runtime dependencies are:

- `langgraph`
- `langchain`
- `langsmith`
- `python-dotenv`
- `typer`

If you want an extra safety check, inspect the resolved dependency tree before publishing:

```bash
pip install -e .
pip show langgraph langchain langsmith python-dotenv typer
pip list
```

### Build the Package

Install build tooling:

```bash
python -m pip install --upgrade build twine
```

Build distributions:

```bash
python -m build
```

This creates files in `dist/`.

### Validate the Distribution

Run:

```bash
python -m twine check dist/*
```

### Publish to TestPyPI

Test the release safely first:

```bash
python -m twine upload --repository testpypi dist/*
```

Then verify install in a clean environment:

```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ langgraph-init-cli
langgraph-init demo-app --template production
```

### Publish to PyPI

When the TestPyPI release looks good:

```bash
python -m twine upload dist/*
```

Users can then install the tool with:

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

Or, for a cleaner CLI-first experience:

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

### Release Checklist

- Bump version in `pyproject.toml`
- Build with `python -m build`
- Validate with `python -m twine check dist/*`
- Upload to TestPyPI
- Smoke test installation
- Upload to PyPI

### Versioning Reminder

PyPI does not allow re-uploading the same version. Every release must use a new version number.
