ddd-agent 0.1.0__tar.gz

ddd_agent-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+site/
+*.egg-info/
+.DS_Store

ddd_agent-0.1.0/LICENSE

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

ddd_agent-0.1.0/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: ddd-agent
+Version: 0.1.0
+Summary: DDD-friendly Python agent template for LangGraph and LangChain applications.
+Project-URL: Homepage, https://github.com/seungbaeji/domain-agent-template
+Project-URL: Repository, https://github.com/seungbaeji/domain-agent-template
+Project-URL: Issues, https://github.com/seungbaeji/domain-agent-template/issues
+Author: Seungbae Ji
+License: MIT License
+        
+        Copyright (c) 2026 Seungbae Ji
+        
+        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.
+License-File: LICENSE
+Keywords: agent,ddd,langchain,langgraph,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: langchain-core>=1.0.0
+Requires-Dist: langgraph>=0.2.0
+Description-Content-Type: text/markdown
+
+# ddd-agent
+
+LangGraph와 LangChain을 적용하기 쉬운 DDD-friendly Python agent 템플릿입니다.
+
+이 저장소는 "LangGraph를 쓰는 샘플"이 아니라, 다음을 분리해서 유지하는 reusable core를 목표로 합니다.
+
+- 도메인 규칙
+- review packet과 review result 같은 사람 개입 모델
+- `AgentEngine` 포트를 통한 agent reasoning 결과 생성
+- LangGraph workflow orchestration
+- LangChain LCEL 기반 `AgentEngine` adapter
+- CLI 기반 human review 데모
+- 외부 example app
+
+## 핵심 포인트
+
+- 패키지 이름: `ddd-agent`
+- import 패키지: `domain_agent`
+- Python: `3.11+`
+- 패키징: `uv`
+- workflow orchestration: `LangGraph`
+- 현재 사람 개입 흐름: `optional human review`
+- 포함된 CLI:
+  - `domain-agent-demo`
+  - `domain-agent-graph`
+
+## 빠른 실행
+
+```bash
+uv sync
+uv run domain-agent-demo
+```
+
+workflow graph 확인:
+
+```bash
+uv run domain-agent-graph --format mermaid
+```
+
+패키지 빌드:
+
+```bash
+uv build
+```
+
+PyPI 배포:
+
+- GitHub Release를 `published` 상태로 만들면 `.github/workflows/release.yml`이 실행됩니다.
+- workflow는 `uv build` 후 Trusted Publishing으로 `ddd-agent`를 PyPI에 업로드합니다.
+- PyPI 쪽 publisher 설정의 project name은 반드시 `ddd-agent`여야 합니다.
+
+## 문서
+
+현재 구조를 이해할 때는 아래 문서를 먼저 보는 편이 좋습니다.
+
+- [Overview](docs/index.md)
+- [Architecture](docs/architecture.md)
+- [Domain Model](docs/domain-model.md)
+- [Package Map](docs/package-map.md)
+- [Runtime Flow](docs/runtime-flow.md)
+- [Extension Guide](docs/extension-guide.md)
+
+읽기 순서 추천:
+
+1. `src/domain_agent/domain/models.py`
+2. `docs/domain-model.md`
+3. `src/domain_agent/application/dto.py`
+4. `src/domain_agent/application/ports.py`
+5. `src/domain_agent/workflow/graph.py`
+6. `src/domain_agent/workflow/nodes/deterministic.py`
+7. `src/domain_agent/application/services.py`
+8. `src/domain_agent/interfaces/cli_demo.py`
+
+## 현재 구조 요약
+
+generic core:
+- `src/domain_agent`
+
+example apps:
+- `examples/autonomous_digest`
+- `examples/operational_change`
+- `examples/mock_api`
+
+현재 human-in-the-loop 메커니즘은 LangGraph interrupt/resume에 위임되어 있습니다.  
+기본 workflow는 human review를 켜거나 끌 수 있고, review가 필요한 경우에만 `ReviewPacket`으로 pause합니다. review를 끄면 같은 lifecycle을 자동 review result로 통과합니다.
+
+현재 core workflow는 아래 단계를 가집니다.
+
+- `validate_request`
+- `collect_context`
+- `prepare_agent_work`
+- `resolve_review`
+- `execute_action`
+- `close_request`
+
+## 도메인 모델
+
+현재 도메인 모델의 중심은 `Request` aggregate입니다.
+
+핵심 타입:
+
+- `Request`
+- `RequestStatus`
+- `RiskLevel`
+- `Proposal`
+- `AgentPlan`
+- `PlannedAction`
+- `ReviewDecision`
+- `ActionReviewDecision`
+- `PlanReviewResult`
+
+의미:
+
+- `Request`는 lifecycle과 review 결과를 소유하는 aggregate root입니다.
+- `Proposal`은 review 대상인 human-readable summary입니다.
+- `AgentPlan`은 실행 가능한 action plan입니다.
+- `PlanReviewResult`는 plan-level 결과와 action-level 결과를 함께 묶습니다.
+
+주요 invariants:
+
+- `PROPOSED` 이후 상태는 반드시 `Proposal`이 있어야 함
+- `APPROVED`, `REJECTED`, `EXECUTED`는 반드시 `ReviewDecision`이 있어야 함
+- action review는 planned action 전체를 정확히 덮어야 함
+- reject된 request는 실행할 수 없음
+- execute는 positive review 이후에만 가능
+
+상세 설명은 [Domain Model](docs/domain-model.md) 문서를 참고하면 됩니다.
+
+## 테스트
+
+generic package:
+
+```bash
+uv run pytest -q tests
+```
+
+example apps:
+
+```bash
+uv run pytest -q examples/autonomous_digest/tests
+uv run pytest -q examples/operational_change/tests
+uv run pytest -q examples/mock_api/tests
+```
+
+## Example Variants
+
+| Example | Human review | Purpose |
+| --- | --- | --- |
+| `examples/autonomous_digest` | disabled | show the same core in autonomous mode |
+| `examples/operational_change` | enabled | show a review-heavy operational workflow |
+| `examples/mock_api` | enabled | show a reviewable flow with a fake external API |
+
+정적 검사:
+
+```bash
+uv run ruff check src tests examples/operational_change examples/mock_api
+uv run mypy src
+```
+
+## 문서 사이트
+
+Python 생태계 쪽 도구를 그대로 쓰기 위해 `MkDocs + mkdocstrings` 구성을 추가했습니다.
+
+설치:
+
+```bash
+make docs-sync
+```
+
+실행:
+
+```bash
+make docs
+```
+
+정적 빌드:
+
+```bash
+make docs-build
+```
+
+설정 파일:
+- `mkdocs.yml`
+
+## 배포 자동화
+
+PyPI 배포 workflow:
+- `.github/workflows/release.yml`
+
+동작 방식:
+
+1. GitHub Release publish
+2. `.python-version` 기준 Python setup 후 `uv build`
+3. `pypa/gh-action-pypi-publish`로 PyPI 업로드
+
+전제 조건:
+
+- PyPI Trusted Publisher 등록
+- project name: `ddd-agent`
+- repository: `seungbaeji/domain-agent-template`
+- workflow filename: `release.yml`

ddd_agent-0.1.0/README.md

@@ -0,0 +1,201 @@
+# ddd-agent
+
+LangGraph와 LangChain을 적용하기 쉬운 DDD-friendly Python agent 템플릿입니다.
+
+이 저장소는 "LangGraph를 쓰는 샘플"이 아니라, 다음을 분리해서 유지하는 reusable core를 목표로 합니다.
+
+- 도메인 규칙
+- review packet과 review result 같은 사람 개입 모델
+- `AgentEngine` 포트를 통한 agent reasoning 결과 생성
+- LangGraph workflow orchestration
+- LangChain LCEL 기반 `AgentEngine` adapter
+- CLI 기반 human review 데모
+- 외부 example app
+
+## 핵심 포인트
+
+- 패키지 이름: `ddd-agent`
+- import 패키지: `domain_agent`
+- Python: `3.11+`
+- 패키징: `uv`
+- workflow orchestration: `LangGraph`
+- 현재 사람 개입 흐름: `optional human review`
+- 포함된 CLI:
+  - `domain-agent-demo`
+  - `domain-agent-graph`
+
+## 빠른 실행
+
+```bash
+uv sync
+uv run domain-agent-demo
+```
+
+workflow graph 확인:
+
+```bash
+uv run domain-agent-graph --format mermaid
+```
+
+패키지 빌드:
+
+```bash
+uv build
+```
+
+PyPI 배포:
+
+- GitHub Release를 `published` 상태로 만들면 `.github/workflows/release.yml`이 실행됩니다.
+- workflow는 `uv build` 후 Trusted Publishing으로 `ddd-agent`를 PyPI에 업로드합니다.
+- PyPI 쪽 publisher 설정의 project name은 반드시 `ddd-agent`여야 합니다.
+
+## 문서
+
+현재 구조를 이해할 때는 아래 문서를 먼저 보는 편이 좋습니다.
+
+- [Overview](docs/index.md)
+- [Architecture](docs/architecture.md)
+- [Domain Model](docs/domain-model.md)
+- [Package Map](docs/package-map.md)
+- [Runtime Flow](docs/runtime-flow.md)
+- [Extension Guide](docs/extension-guide.md)
+
+읽기 순서 추천:
+
+1. `src/domain_agent/domain/models.py`
+2. `docs/domain-model.md`
+3. `src/domain_agent/application/dto.py`
+4. `src/domain_agent/application/ports.py`
+5. `src/domain_agent/workflow/graph.py`
+6. `src/domain_agent/workflow/nodes/deterministic.py`
+7. `src/domain_agent/application/services.py`
+8. `src/domain_agent/interfaces/cli_demo.py`
+
+## 현재 구조 요약
+
+generic core:
+- `src/domain_agent`
+
+example apps:
+- `examples/autonomous_digest`
+- `examples/operational_change`
+- `examples/mock_api`
+
+현재 human-in-the-loop 메커니즘은 LangGraph interrupt/resume에 위임되어 있습니다.  
+기본 workflow는 human review를 켜거나 끌 수 있고, review가 필요한 경우에만 `ReviewPacket`으로 pause합니다. review를 끄면 같은 lifecycle을 자동 review result로 통과합니다.
+
+현재 core workflow는 아래 단계를 가집니다.
+
+- `validate_request`
+- `collect_context`
+- `prepare_agent_work`
+- `resolve_review`
+- `execute_action`
+- `close_request`
+
+## 도메인 모델
+
+현재 도메인 모델의 중심은 `Request` aggregate입니다.
+
+핵심 타입:
+
+- `Request`
+- `RequestStatus`
+- `RiskLevel`
+- `Proposal`
+- `AgentPlan`
+- `PlannedAction`
+- `ReviewDecision`
+- `ActionReviewDecision`
+- `PlanReviewResult`
+
+의미:
+
+- `Request`는 lifecycle과 review 결과를 소유하는 aggregate root입니다.
+- `Proposal`은 review 대상인 human-readable summary입니다.
+- `AgentPlan`은 실행 가능한 action plan입니다.
+- `PlanReviewResult`는 plan-level 결과와 action-level 결과를 함께 묶습니다.
+
+주요 invariants:
+
+- `PROPOSED` 이후 상태는 반드시 `Proposal`이 있어야 함
+- `APPROVED`, `REJECTED`, `EXECUTED`는 반드시 `ReviewDecision`이 있어야 함
+- action review는 planned action 전체를 정확히 덮어야 함
+- reject된 request는 실행할 수 없음
+- execute는 positive review 이후에만 가능
+
+상세 설명은 [Domain Model](docs/domain-model.md) 문서를 참고하면 됩니다.
+
+## 테스트
+
+generic package:
+
+```bash
+uv run pytest -q tests
+```
+
+example apps:
+
+```bash
+uv run pytest -q examples/autonomous_digest/tests
+uv run pytest -q examples/operational_change/tests
+uv run pytest -q examples/mock_api/tests
+```
+
+## Example Variants
+
+| Example | Human review | Purpose |
+| --- | --- | --- |
+| `examples/autonomous_digest` | disabled | show the same core in autonomous mode |
+| `examples/operational_change` | enabled | show a review-heavy operational workflow |
+| `examples/mock_api` | enabled | show a reviewable flow with a fake external API |
+
+정적 검사:
+
+```bash
+uv run ruff check src tests examples/operational_change examples/mock_api
+uv run mypy src
+```
+
+## 문서 사이트
+
+Python 생태계 쪽 도구를 그대로 쓰기 위해 `MkDocs + mkdocstrings` 구성을 추가했습니다.
+
+설치:
+
+```bash
+make docs-sync
+```
+
+실행:
+
+```bash
+make docs
+```
+
+정적 빌드:
+
+```bash
+make docs-build
+```
+
+설정 파일:
+- `mkdocs.yml`
+
+## 배포 자동화
+
+PyPI 배포 workflow:
+- `.github/workflows/release.yml`
+
+동작 방식:
+
+1. GitHub Release publish
+2. `.python-version` 기준 Python setup 후 `uv build`
+3. `pypa/gh-action-pypi-publish`로 PyPI 업로드
+
+전제 조건:
+
+- PyPI Trusted Publisher 등록
+- project name: `ddd-agent`
+- repository: `seungbaeji/domain-agent-template`
+- workflow filename: `release.yml`

ddd_agent-0.1.0/pyproject.toml

@@ -0,0 +1,101 @@
+[project]
+name = "ddd-agent"
+version = "0.1.0"
+description = "DDD-friendly Python agent template for LangGraph and LangChain applications."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Seungbae Ji" },
+]
+keywords = ["agent", "langgraph", "langchain", "ddd", "workflow"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "langchain-core>=1.0.0",
+  "langgraph>=0.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/seungbaeji/domain-agent-template"
+Repository = "https://github.com/seungbaeji/domain-agent-template"
+Issues = "https://github.com/seungbaeji/domain-agent-template/issues"
+
+[project.scripts]
+domain-agent-demo = "domain_agent.interfaces.cli_demo:main"
+domain-agent-graph = "domain_agent.interfaces.cli_graph:main"
+
+[dependency-groups]
+dev = [
+  "build>=1.2.2",
+  "mypy>=1.11.0",
+  "pytest>=8.3.0",
+  "ruff>=0.6.0",
+]
+docs = [
+  "mkdocs>=1.6.0",
+  "mkdocs-material>=9.5.0",
+  "mkdocs-mermaid2-plugin>=1.2.1",
+  "mkdocstrings[python]>=0.26.0",
+]
+
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/domain_agent"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/LICENSE",
+  "/README.md",
+  "/pyproject.toml",
+  "/src/domain_agent",
+]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = [
+  "-ra",
+  "--strict-config",
+  "--strict-markers",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+  "E",
+  "F",
+  "I",
+  "B",
+  "UP",
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.mypy]
+python_version = "3.11"
+mypy_path = "src"
+packages = ["domain_agent"]
+strict = true
+warn_unused_configs = true
+
+[tool.uv]
+package = true

ddd_agent-0.1.0/src/domain_agent/__init__.py

@@ -0,0 +1,12 @@
+"""DDD-friendly agent template package."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("ddd-agent")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

ddd_agent-0.1.0/src/domain_agent/application/__init__.py

@@ -0,0 +1 @@
+"""Application layer package."""

ddd_agent-0.1.0/src/domain_agent/application/dto.py

@@ -0,0 +1,74 @@
+"""Application-layer data structures."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from domain_agent.domain import (
+    ActionReviewDecision,
+    AgentPlan,
+    PlannedAction,
+    Proposal,
+    Request,
+    RiskLevel,
+)
+
+
+@dataclass(frozen=True)
+class AnalysisResult:
+    """Structured analysis output used to build a proposal."""
+
+    summary: str
+    rationale: str
+    execution_steps: tuple[str, ...]
+    risk_level: RiskLevel
+
+
+@dataclass(frozen=True)
+class AgentWorkResult:
+    """Structured output returned by an agent engine."""
+
+    analysis: AnalysisResult
+    proposal: Proposal
+    agent_plan: AgentPlan | None = None
+
+
+@dataclass(frozen=True)
+class ReviewPacket:
+    """Structured payload presented to a human reviewer."""
+
+    request_id: str
+    requester_id: str
+    request_summary: str
+    proposal_summary: str
+    rationale: str
+    risk_level: RiskLevel
+    execution_steps: tuple[str, ...]
+    planned_actions: tuple[PlannedAction, ...]
+    action_decisions: tuple[ActionReviewDecision, ...] = ()
+
+
+def build_review_packet(request: Request, proposal: Proposal) -> ReviewPacket:
+    """Create a structured review packet from the request and proposal."""
+    planned_actions: tuple[PlannedAction, ...]
+    if proposal.agent_plan is not None:
+        planned_actions = proposal.agent_plan.actions
+    else:
+        planned_actions = (
+            PlannedAction(
+                action_id="plan-review",
+                tool_name="plan_review",
+                description="Review the overall proposal as a single action.",
+            ),
+        )
+
+    return ReviewPacket(
+        request_id=request.request_id,
+        requester_id=request.requester_id,
+        request_summary=request.summary,
+        proposal_summary=proposal.summary,
+        rationale=proposal.rationale,
+        risk_level=proposal.risk_level,
+        execution_steps=proposal.execution_steps,
+        planned_actions=planned_actions,
+    )