devflow-toolkit 0.3.0__py3-none-any.whl

devflow/core/state/models.py

@@ -0,0 +1,164 @@
+"""Workflow state models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from devflow.core.artifacts.models import ArtifactRecord
+
+
+class WorkflowStatus(str, Enum):
+  """State of a change in the DevFlow lifecycle."""
+
+  DRAFT = "draft"
+  AWAITING_CLARIFICATION = "awaiting_clarification"
+  SPEC_APPROVED = "spec_approved"
+  PLANNED = "planned"
+  PLAN_APPROVED = "plan_approved"
+  IMPLEMENTING = "implementing"
+  IMPLEMENTED = "implemented"
+  REVIEWED = "reviewed"
+  REVIEW_APPROVED = "review_approved"
+  CHANGES_REQUESTED = "changes_requested"
+  DONE = "done"
+
+
+WORKFLOW_STATUSES = tuple(status.value for status in WorkflowStatus)
+
+STAGE_TARGETS = {
+  "spec": WorkflowStatus.SPEC_APPROVED.value,
+  "plan": WorkflowStatus.PLAN_APPROVED.value,
+  "review": WorkflowStatus.REVIEW_APPROVED.value,
+}
+
+STAGE_ARTIFACTS = {
+  "spec": ("spec",),
+  "discovery": ("discovery",),
+  "plan": ("plan", "tasks"),
+  "review": ("review",),
+}
+
+# Discovery is approved together with the specification it informed.
+# Legacy changes created before Discovery have no such artifact.
+STAGE_OPTIONAL_ARTIFACTS = {
+  "spec": ("discovery",),
+}
+
+
+@dataclass(frozen=True)
+class ApprovalRecord:
+  """A human approval bound to one or more artifact digests."""
+
+  stage: str
+  by: str
+  at: str
+  artifacts: dict[str, str] = field(default_factory=dict)
+  architecture_digest: str = ""
+
+  def to_dict(self) -> dict[str, Any]:
+    return {
+      "by": self.by,
+      "at": self.at,
+      "artifacts": dict(self.artifacts),
+      "architecture_digest": self.architecture_digest,
+    }
+
+  @classmethod
+  def from_dict(
+    cls,
+    stage: str,
+    data: dict[str, Any],
+  ) -> ApprovalRecord:
+    artifacts = data.get("artifacts") or {}
+    if not isinstance(artifacts, dict):
+      artifacts = {}
+    return cls(
+      stage=stage,
+      by=str(data.get("by", "user")),
+      at=str(data.get("at", "")),
+      artifacts={
+        str(key): str(value)
+        for key, value in artifacts.items()
+      },
+      architecture_digest=str(data.get("architecture_digest", "")),
+    )
+
+
+@dataclass
+class WorkflowState:
+  """Current projection of a change workflow."""
+
+  version: int = 1
+  spec_id: str = ""
+  change: str = ""
+  status: str = WorkflowStatus.DRAFT.value
+  created_at: str = ""
+  updated_at: str = ""
+  last_event_seq: int = 0
+  artifacts: dict[str, ArtifactRecord] = field(default_factory=dict)
+  approvals: dict[str, ApprovalRecord] = field(default_factory=dict)
+  current_implementation: str | None = None
+  current_review: str | None = None
+
+  def to_dict(self) -> dict[str, Any]:
+    return {
+      "version": self.version,
+      "spec_id": self.spec_id,
+      "change": self.change,
+      "status": self.status,
+      "created_at": self.created_at,
+      "updated_at": self.updated_at,
+      "last_event_seq": self.last_event_seq,
+      "artifacts": {
+        key: record.to_dict()
+        for key, record in sorted(self.artifacts.items())
+      },
+      "approvals": {
+        key: approval.to_dict()
+        for key, approval in sorted(self.approvals.items())
+      },
+      "current_implementation": self.current_implementation,
+      "current_review": self.current_review,
+    }
+
+  @classmethod
+  def from_dict(cls, data: dict[str, Any]) -> WorkflowState:
+    artifacts_data = data.get("artifacts") or {}
+    approvals_data = data.get("approvals") or {}
+    artifacts: dict[str, ArtifactRecord] = {}
+    approvals: dict[str, ApprovalRecord] = {}
+    if isinstance(artifacts_data, dict):
+      for key, value in artifacts_data.items():
+        if isinstance(value, dict):
+          artifacts[str(key)] = ArtifactRecord.from_dict(value)
+    if isinstance(approvals_data, dict):
+      for key, value in approvals_data.items():
+        if isinstance(value, dict):
+          approvals[str(key)] = ApprovalRecord.from_dict(
+            str(key),
+            value,
+          )
+    return cls(
+      version=int(data.get("version", 1)),
+      spec_id=str(data.get("spec_id", "")),
+      change=str(data.get("change", "")),
+      status=str(data.get("status", WorkflowStatus.DRAFT.value)),
+      created_at=str(data.get("created_at", "")),
+      updated_at=str(data.get("updated_at", "")),
+      last_event_seq=int(data.get("last_event_seq", 0)),
+      artifacts=artifacts,
+      approvals=approvals,
+      current_implementation=_optional_string(
+        data.get("current_implementation")
+      ),
+      current_review=_optional_string(data.get("current_review")),
+    )
+
+
+def _optional_string(value: Any) -> str | None:
+  if value is None:
+    return None
+  text = str(value)
+  return text or None

devflow/core/state/transitions.py

@@ -0,0 +1,114 @@
+"""Allowed workflow transitions and their artifact requirements."""
+
+from __future__ import annotations
+
+from devflow.core.artifacts.models import ArtifactStatus
+from devflow.core.state.errors import InvalidTransitionError
+from devflow.core.state.models import WorkflowState, WorkflowStatus
+
+
+ALLOWED_TRANSITIONS: dict[str, frozenset[str]] = {
+  WorkflowStatus.DRAFT.value: frozenset(
+    {
+      WorkflowStatus.AWAITING_CLARIFICATION.value,
+      WorkflowStatus.SPEC_APPROVED.value,
+    }
+  ),
+  WorkflowStatus.AWAITING_CLARIFICATION.value: frozenset(
+    {WorkflowStatus.DRAFT.value}
+  ),
+  WorkflowStatus.SPEC_APPROVED.value: frozenset(
+    {WorkflowStatus.PLANNED.value}
+  ),
+  WorkflowStatus.PLANNED.value: frozenset(
+    {WorkflowStatus.PLAN_APPROVED.value}
+  ),
+  WorkflowStatus.PLAN_APPROVED.value: frozenset(
+    {WorkflowStatus.IMPLEMENTING.value}
+  ),
+  WorkflowStatus.IMPLEMENTING.value: frozenset(
+    {
+      WorkflowStatus.IMPLEMENTED.value,
+      WorkflowStatus.CHANGES_REQUESTED.value,
+    }
+  ),
+  WorkflowStatus.IMPLEMENTED.value: frozenset(
+    {WorkflowStatus.REVIEWED.value}
+  ),
+  WorkflowStatus.REVIEWED.value: frozenset(
+    {
+      WorkflowStatus.REVIEW_APPROVED.value,
+      WorkflowStatus.CHANGES_REQUESTED.value,
+    }
+  ),
+  WorkflowStatus.REVIEW_APPROVED.value: frozenset(
+    {WorkflowStatus.DONE.value}
+  ),
+  WorkflowStatus.CHANGES_REQUESTED.value: frozenset(
+    {WorkflowStatus.IMPLEMENTING.value}
+  ),
+  WorkflowStatus.DONE.value: frozenset(),
+}
+
+TARGET_ARTIFACTS: dict[str, tuple[str, ...]] = {
+  WorkflowStatus.SPEC_APPROVED.value: ("spec",),
+  WorkflowStatus.PLANNED.value: ("spec",),
+  WorkflowStatus.PLAN_APPROVED.value: ("spec", "plan"),
+  WorkflowStatus.IMPLEMENTING.value: ("spec", "plan"),
+  WorkflowStatus.IMPLEMENTED.value: ("spec", "plan"),
+  WorkflowStatus.REVIEWED.value: ("spec", "plan"),
+  WorkflowStatus.REVIEW_APPROVED.value: ("spec", "plan", "review"),
+  WorkflowStatus.CHANGES_REQUESTED.value: ("spec", "plan"),
+  WorkflowStatus.DONE.value: ("spec", "plan", "review"),
+}
+
+
+def can_transition(current: str, target: str) -> bool:
+  """Return whether a workflow may move from one state to another."""
+  if current == target:
+    return True
+  return target in ALLOWED_TRANSITIONS.get(current, frozenset())
+
+
+def ensure_transition(current: str, target: str) -> None:
+  """Raise when a workflow transition is not allowed."""
+  if can_transition(current, target):
+    return
+  msg = (
+    f"Invalid workflow transition: {current} -> {target}. "
+    "Resolve the current stage before advancing."
+  )
+  raise InvalidTransitionError(msg)
+
+
+def required_artifacts(target: str) -> tuple[str, ...]:
+  """Return artifact kinds required before entering a target state."""
+  return TARGET_ARTIFACTS.get(target, ())
+
+
+def artifact_blockers(
+  state: WorkflowState,
+  target: str,
+) -> tuple[str, ...]:
+  """Return artifact kinds that are not approved for a target state."""
+  blockers: list[str] = []
+  for kind in required_artifacts(target):
+    record = state.artifacts.get(kind)
+    if record is None:
+      blockers.append(f"{kind} (missing)")
+    elif record.status != ArtifactStatus.APPROVED.value:
+      blockers.append(f"{kind} ({record.status})")
+  return tuple(blockers)
+
+
+def ensure_artifacts_ready(state: WorkflowState, target: str) -> None:
+  """Raise when required artifacts are not approved."""
+  blockers = artifact_blockers(state, target)
+  if not blockers:
+    return
+  msg = (
+    f"Cannot enter {target}: required artifacts are not approved: "
+    + ", ".join(blockers)
+    + "."
+  )
+  raise InvalidTransitionError(msg)

devflow/models/__init__.py

@@ -0,0 +1,6 @@
+"""Data models used by DevFlow."""
+
+from devflow.models.profile import Profile
+from devflow.models.project import Project
+
+__all__ = ["Profile", "Project"]

devflow/models/profile.py

@@ -0,0 +1,63 @@
+"""Project profile data model."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Profile:
+  """A reusable project profile bundled with DevFlow."""
+
+  name: str
+  version: str
+  description: str
+  path: Path
+  constitution: tuple[str, ...] = field(default_factory=tuple)
+  templates: tuple[str, ...] = field(default_factory=tuple)
+  technologies: tuple[str, ...] = field(default_factory=tuple)
+  detection_files: tuple[str, ...] = field(default_factory=tuple)
+  detection_dependencies: tuple[str, ...] = field(default_factory=tuple)
+  detection_indicators: tuple[str, ...] = field(default_factory=tuple)
+
+  @classmethod
+  def from_manifest(
+    cls,
+    path: Path,
+    data: dict[str, Any],
+  ) -> "Profile":
+    """Build a profile from a profile.yaml manifest."""
+    detection = data.get("detection") or {}
+    if not isinstance(detection, dict):
+      msg = "Profile detection must be a mapping."
+      raise ValueError(msg)
+
+    name = data.get("name")
+    if not isinstance(name, str) or not name:
+      msg = "Profile manifest must define a non-empty name."
+      raise ValueError(msg)
+
+    def string_tuple(value: Any) -> tuple[str, ...]:
+      if value is None:
+        return ()
+      if not isinstance(value, list):
+        msg = f"Profile field must be a list: {value!r}"
+        raise ValueError(msg)
+      return tuple(str(item) for item in value)
+
+    return cls(
+      name=name,
+      version=str(data.get("version", "0.0.0")),
+      description=str(data.get("description", "")),
+      path=path,
+      constitution=string_tuple(data.get("constitution")),
+      templates=string_tuple(data.get("templates")),
+      technologies=string_tuple(data.get("technologies")),
+      detection_files=string_tuple(detection.get("files")),
+      detection_dependencies=string_tuple(
+        detection.get("dependencies")
+      ),
+      detection_indicators=string_tuple(
+        detection.get("indicators")
+      ),
+    )

devflow/models/project.py

@@ -0,0 +1,47 @@
+"""Detected project data model and project modes."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+
+class ProjectMode(str, Enum):
+  """Context used to prepare one specification."""
+
+  EXISTING = "existing"
+  GREENFIELD = "greenfield"
+
+
+PROJECT_MODES = tuple(mode.value for mode in ProjectMode)
+
+
+def canonical_project_mode(value: str) -> str:
+  """Normalize a project mode name."""
+  return value.strip().lower().replace("_", "-")
+
+
+@dataclass
+class Project:
+  """A software project inspected by DevFlow."""
+
+  root: Path
+  name: str
+  project_type: str
+  languages: list[str] = field(default_factory=list)
+  frameworks: list[str] = field(default_factory=list)
+  databases: list[str] = field(default_factory=list)
+  dependencies: set[str] = field(default_factory=set)
+  manifests: list[str] = field(default_factory=list)
+  source_files: list[str] = field(default_factory=list)
+  profiles: list[str] = field(default_factory=list)
+
+  def to_config(self, profiles: list[str]) -> dict:
+    """Return the persistent project section for config.yaml."""
+    return {
+      "name": self.name,
+      "type": self.project_type,
+      "languages": self.languages,
+      "frameworks": self.frameworks,
+      "databases": self.databases,
+      "profiles": profiles,
+    }

devflow/profiles/ai-rag/constitution/ai-rag-standards.md

@@ -0,0 +1,49 @@
+# AI and RAG Development Standards
+
+## 1. Retrieval Quality
+
+- Define measurable retrieval quality expectations.
+- Preserve document metadata used for filtering and citation.
+- Evaluate changes to chunking, embeddings and ranking.
+- Avoid mixing incompatible embedding models or dimensions.
+- Test retrieval with representative queries and edge cases.
+
+## 2. Data and Ingestion
+
+- Make ingestion idempotent where possible.
+- Track document identity, source and version.
+- Handle malformed, empty and duplicate documents.
+- Respect data privacy, retention and access rules.
+- Avoid logging sensitive document content by default.
+
+## 3. Prompts and Generation
+
+- Keep prompts versioned and reviewed.
+- Separate system instructions from user content.
+- Treat retrieved content as untrusted input.
+- Require citations when answers depend on retrieved context.
+- Define behavior when no relevant context is found.
+
+## 4. Vector Stores
+
+- Use the existing vector store abstraction.
+- Consider collection isolation and access control.
+- Define index creation and migration procedures.
+- Handle unavailable or partially available stores.
+- Monitor latency, recall and storage growth.
+
+## 5. Model Integrations
+
+- Isolate providers behind adapters or service boundaries.
+- Configure timeouts, retries and fallback behavior.
+- Avoid hard-coding model names, keys or endpoints.
+- Track token usage and cost where appropriate.
+- Handle provider errors without exposing secrets.
+
+## 6. Evaluation and Testing
+
+- Add offline evaluation for retrieval and answer quality.
+- Use deterministic fixtures for unit tests.
+- Separate evaluation data from production data.
+- Track regressions when changing models or prompts.
+- Document assumptions and known limitations.

devflow/profiles/ai-rag/profile.yaml

@@ -0,0 +1,28 @@
+name: ai-rag
+version: "1.0.0"
+description: AI and retrieval-augmented generation profile.
+
+detection:
+  files: []
+  dependencies:
+    - langchain
+    - llama-index
+    - chromadb
+    - faiss-cpu
+    - qdrant-client
+    - sentence-transformers
+  indicators:
+    - vector_database
+    - embeddings
+    - retrieval_pipeline
+
+constitution:
+  - ai-rag-standards.md
+
+templates: []
+
+technologies:
+  - python
+  - artificial-intelligence
+  - rag
+  - vector-databases

devflow/profiles/base/constitution/architecture.md

@@ -0,0 +1,58 @@
+# Architecture Guidelines
+
+## 1. Design Principles
+
+- Apply SOLID principles when they provide clear value.
+- Maintain separation of concerns.
+- Prefer modular and loosely coupled components.
+- Keep business logic independent from infrastructure
+  when appropriate.
+- Avoid unnecessary abstractions and complexity.
+
+## 2. Business Logic
+
+- Place business logic in the component responsible
+  for the corresponding domain.
+- Avoid duplicating business rules.
+- Reuse existing services and domain components
+  whenever appropriate.
+- Keep controllers and API views focused on
+  request handling and response generation.
+
+## 3. Data Access
+
+- Optimize database access according to the actual
+  query requirements.
+- Avoid N+1 query problems.
+- Retrieve only the data required by the operation.
+- Use appropriate database indexes and constraints.
+- Consider transaction boundaries and data integrity.
+
+## 4. Integration and Communication
+
+- Isolate external integrations behind appropriate
+  interfaces or service components.
+- Handle timeouts, connection errors and unexpected
+  responses.
+- Consider retries and recovery mechanisms when needed.
+- Avoid tightly coupling internal business logic
+  to external API implementations.
+
+## 5. Reliability
+
+- Consider partial failures and unexpected execution
+  states.
+- Preserve data consistency.
+- Avoid duplicate processing where operations can
+  be repeated.
+- Implement observability and traceability when
+  appropriate.
+
+## 6. Performance
+
+- Identify actual performance bottlenecks before
+  optimizing.
+- Avoid unnecessary database queries and processing.
+- Prefer efficient data access patterns.
+- Consider asynchronous processing for workloads
+  that justify it.

devflow/profiles/base/constitution/code-standards.md

@@ -0,0 +1,85 @@
+# Code Standards
+
+## 1. General Principles
+
+- Follow clean code principles and language conventions.
+- Prioritize readability and maintainability.
+- Use descriptive names for variables, functions and classes.
+- Avoid unnecessary abbreviations.
+- Avoid over-engineering.
+
+## 2. Formatting
+
+- Maximum line length: 79 characters.
+- Use 2 spaces for indentation.
+- Never use tabs.
+- Keep formatting consistent across the project.
+- If a statement exceeds the maximum line length,
+  split it into multiple lines.
+
+Note: The 2-space indentation is a project-specific
+convention and overrides the default PEP 8 indentation
+recommendation.
+
+## 3. Imports
+
+- Use absolute imports within the project.
+- Never use relative imports between project modules.
+- Follow this import order:
+  1. Python standard library.
+  2. Third-party libraries.
+  3. Framework imports, when applicable.
+  4. Local project imports.
+- Sort imports alphabetically within each group.
+
+Example:
+
+    import logging
+    from typing import Any
+
+    import requests
+
+    from framework import transaction
+
+    from project.models.entity import Entity
+
+## 4. Naming Conventions
+
+- Use descriptive names for variables and functions.
+- Use PascalCase for classes.
+- Use snake_case for variables, functions and modules.
+- Boolean variables should use prefixes such as:
+  is_, has_, can_ or should_.
+- Avoid ambiguous or overly abbreviated names.
+
+## 5. Type Hints
+
+- Add type hints to function parameters.
+- Add return type annotations to functions.
+- Use typing for complex types when appropriate.
+- Use Any from the typing module when a dynamic
+  type is genuinely necessary.
+- Avoid using Any when a more precise type is possible.
+
+## 6. Comments and Documentation
+
+- Write code, comments, docstrings and technical
+  documentation in English.
+- Use Spanish only for user-facing content when needed.
+- Avoid comments that merely repeat the code.
+- Explain complex logic, non-obvious decisions
+  and important edge cases.
+- Add docstrings to public APIs, complex functions
+  and non-obvious classes.
+- Use Google-style docstrings.
+- Avoid unnecessary docstrings for simple functions
+  and standard framework patterns.
+
+## 7. Function Design
+
+- Keep functions focused on a single responsibility.
+- Avoid unnecessarily large functions.
+- When a function has more than two parameters,
+  place each parameter on a separate line.
+- Apply the same multiline formatting when a function
+  declaration exceeds the maximum line length.