odd-org 0.1.0__py3-none-any.whl

odd/__init__.py

@@ -0,0 +1,3 @@
+"""ODD - Organization Driven Development."""
+
+__version__ = "0.1.0"

odd/__main__.py

@@ -0,0 +1,20 @@
+"""Allow running as python -m odd."""
+
+import random
+import sys
+
+from rich.console import Console
+
+
+def _run() -> None:
+    from odd.cli import CLOSING_REMARKS, main
+
+    try:
+        main()
+    except KeyboardInterrupt:
+        console = Console()
+        console.print(f"\n[bold yellow]{random.choice(CLOSING_REMARKS)}[/bold yellow]")
+        sys.exit(0)
+
+
+_run()

odd/agent.py

@@ -0,0 +1,394 @@
+"""Agent invocation engine - the core of ODD.
+
+Each agent is a strictly isolated API call. The system prompt is built
+entirely from the persona's files (JD, resume, notes). No context bleeds
+between agents.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable
+
+from odd.config import DEFAULT_MAX_TOKENS
+from odd.fallback.runner import (  # noqa: F401 - re-exported for backwards compat
+    AgentKilledError,
+    AgentStuckError,
+    BudgetExceededError,
+    DirectRunner,
+    MaxIterationsError,
+)
+from odd.middleware import WRAP_UP_NOTICE, RunnerMiddleware  # noqa: F401 - WRAP_UP_NOTICE re-exported
+from odd.models import Persona, RoleType
+from odd.provider import Provider, StreamCallback, StreamEvent, StreamEventType
+from odd.tools import TOOL_DEFINITIONS
+from odd.tracing import log_stream_event
+
+
+# System prompt templates per role
+ROLE_PREAMBLES: dict[RoleType, str] = {
+    RoleType.LEAD_DEV: (
+        "You are the Lead Developer of this project. You are the primary point of "
+        "contact for the CEO and the technical authority on all decisions. You delegate "
+        "work to consultants, coordinate with QA on test requirements, and drive the "
+        "sprint forward. You write code, review architecture, and make sure the project "
+        "stays on track.\n\n"
+        "You communicate clearly and concisely with the CEO. When you need specialized "
+        "work done, you prepare clear briefs for consultants. You never pretend to be "
+        "a consultant or take on their specialized perspective - you are the generalist "
+        "technical leader."
+    ),
+    RoleType.QA: (
+        "You are the QA Engineer - the infamous Glitch Hunter. Your job is to break "
+        "things. You write tests FIRST (TDD), before any implementation happens. You "
+        "think adversarially: what edge cases will fail? What assumptions are wrong? "
+        "What will users do that developers don't expect?\n\n"
+        "You write thorough, well-structured tests that serve as the specification for "
+        "what 'done' looks like. Your tests are the quality gate - code that passes your "
+        "tests ships. Code that doesn't, gets sent back.\n\n"
+        "You take pride in finding bugs others miss. You are relentless but fair."
+    ),
+    RoleType.RECRUITER: (
+        "You are the Recruiter. When the team needs specialized expertise, you receive "
+        "a job description and craft the perfect candidate - someone whose background, "
+        "skills, and perspective are exactly what the project needs.\n\n"
+        "Given a job description, you produce a detailed resume/profile for the ideal "
+        "consultant. This profile will be used to instantiate an AI agent with that "
+        "expertise, so be specific about their skills, experience, approach, and the "
+        "unique perspective they bring."
+    ),
+    RoleType.SECRETARY: (
+        "You are the Secretary. You keep the organization running smoothly. You take "
+        "notes during standups, maintain project documentation, organize files, track "
+        "decisions, and ensure nothing falls through the cracks.\n\n"
+        "You produce clear, structured summaries. You flag items that need the CEO's "
+        "attention. You keep the .odd/ directory organized and up to date."
+    ),
+    RoleType.CONSULTANT: (
+        "You are a Consultant brought in for your specialized expertise. You focus "
+        "exclusively on your area of knowledge and see the project through that lens. "
+        "You do not try to be a generalist - your value is your specific perspective.\n\n"
+        "You write code, provide recommendations, and complete tasks within your "
+        "specialty. You defer to the Lead Developer on architectural decisions outside "
+        "your expertise."
+    ),
+}
+
+
+def build_system_prompt(
+    persona: Persona,
+    project_context: str = "",
+    company_values: str = "",
+    tools: bool = True,
+    working_dir: str = "",
+) -> str:
+    """Build a complete system prompt from a persona's identity.
+
+    This is the isolation boundary. Each agent sees ONLY:
+    - Their role preamble
+    - Company values (shared across all agents)
+    - Their job description
+    - Their resume
+    - Current project context (shared state, not other agents' conversations)
+    """
+    parts = [ROLE_PREAMBLES[persona.role_type]]
+
+    if company_values:
+        parts.append(company_values)
+
+    if persona.job_description:
+        parts.append(f"## Your Job Description\n{persona.job_description}")
+
+    if persona.resume:
+        parts.append(f"## Your Background\n{persona.resume}")
+
+    if project_context:
+        parts.append(f"## Project Context\n{project_context}")
+
+    if tools:
+        cwd_note = f" Your working directory is: {working_dir}" if working_dir else ""
+        parts.append(
+            "## Working Directory\n"
+            "You are working in the project directory. Use the provided tools to read, "
+            "write, and edit files. Run shell commands as needed. Always use relative "
+            "paths (e.g. src/app.py, tests/test_foo.py) - never construct absolute paths "
+            "yourself." + cwd_note
+        )
+    else:
+        parts.append(
+            "## Working Directory\n"
+            "You are working in the project directory. You do not have tools available "
+            "in this conversation - respond conversationally. Do NOT emit tool calls or "
+            "XML tags."
+        )
+
+    return "\n\n".join(parts)
+
+
+def load_persona_notes(persona: Persona, notes_dir: Path) -> str:
+    """Load any personal notes the agent has kept."""
+    if not notes_dir.exists():
+        return ""
+    notes = []
+    for f in sorted(notes_dir.glob("*.md")):
+        content = f.read_text(encoding="utf-8")
+        notes.append(f"### {f.stem}\n{content}")
+    return "\n\n".join(notes)
+
+
+def _wrap_stream_debug(
+    agent_name: str,
+    inner: StreamCallback | None,
+) -> StreamCallback:
+    """Wrap a stream callback to log every event to stream_debug.jsonl.
+
+    If inner is None, creates a log-only callback (so debug mode always
+    forces streaming on, which is crucial for diagnosing "nothing streams").
+    """
+    def _debug_callback(event: StreamEvent) -> None:
+        kwargs: dict = {"agent_name": agent_name, "event_type": event.event_type.value}
+
+        if event.event_type == StreamEventType.TEXT_DELTA:
+            kwargs["text"] = event.text
+        elif event.event_type == StreamEventType.TOOL_USE_START:
+            kwargs["tool_name"] = event.tool_name
+            kwargs["tool_id"] = event.tool_id
+        elif event.event_type == StreamEventType.TOOL_INPUT_DELTA:
+            kwargs["text"] = event.text
+        elif event.event_type == StreamEventType.TOOL_USE_END:
+            if event.tool_call:
+                kwargs["tool_name"] = event.tool_call.name
+                kwargs["tool_id"] = event.tool_call.id
+                kwargs["tool_input"] = event.tool_call.input
+        elif event.event_type == StreamEventType.MESSAGE_STOP:
+            if event.response:
+                kwargs["stop_reason"] = event.response.stop_reason
+                if event.response.usage:
+                    kwargs["input_tokens"] = event.response.usage.input_tokens
+                    kwargs["output_tokens"] = event.response.usage.output_tokens
+
+        log_stream_event(**kwargs)
+
+        if inner is not None:
+            inner(event)
+
+    return _debug_callback
+
+
+class AgentEngine:
+    """Invokes agents as isolated LLM API calls.
+
+    Builds the system prompt and conversation, then delegates execution
+    to DirectRunner via the Provider protocol.
+    """
+
+    def __init__(
+        self,
+        provider: Provider,
+        cfo: Any | None = None,
+        current_sprint: int | None = None,
+        company_values: str = "",
+        default_stream_factory: Callable[[str], StreamCallback | None] | None = None,
+        debug: bool = False,
+    ):
+        self.provider = provider
+        self.cfo = cfo
+        self.current_sprint = current_sprint
+        self.company_values = company_values
+        self.default_stream_factory = default_stream_factory
+        self.debug = debug
+        self.escalations: list[dict] = []
+        self.submissions: list[dict] = []
+        self.working_dir: Path | None = None
+
+    def fork(self, working_dir: Path | None = None) -> AgentEngine:
+        """Create an independent copy for concurrent task execution.
+
+        The forked engine shares the provider but has its own
+        escalation/submission lists, so concurrent invocations don't
+        interfere. If working_dir is set, tool execution happens there
+        instead of the process cwd.
+
+        Note: the forked engine's escalation and submission lists are
+        NOT thread-safe. Callers must only read them (via
+        get_escalations / get_submissions) AFTER the worker thread has
+        completed. This is currently guaranteed by the ``as_completed``
+        loop in sprint.py.
+        """
+        forked = AgentEngine(
+            provider=self.provider,
+            cfo=self.cfo,
+            current_sprint=self.current_sprint,
+            company_values=self.company_values,
+            default_stream_factory=self.default_stream_factory,
+            debug=self.debug,
+        )
+        forked.working_dir = working_dir
+        return forked
+
+    def get_escalations(self) -> list[dict]:
+        """Get and clear pending escalations captured from agent tool calls."""
+        escalations = list(self.escalations)
+        self.escalations.clear()
+        return escalations
+
+    def get_submissions(self) -> list[dict]:
+        """Get and clear pending structured submissions from agent tool calls."""
+        submissions = list(self.submissions)
+        self.submissions.clear()
+        return submissions
+
+    def pop_submissions(self, tool_name: str) -> list[dict]:
+        """Remove and return submissions matching *tool_name*."""
+        matched = [s for s in self.submissions if s["tool"] == tool_name]
+        self.submissions = [s for s in self.submissions if s["tool"] != tool_name]
+        return matched
+
+    def conversation(
+        self,
+        persona: Persona,
+        *,
+        project_context: str = "",
+        tools: bool = True,
+        extra_tools: list[dict[str, Any]] | None = None,
+        model_override: str | None = None,
+        cancel_check: Callable[[], bool] | None = None,
+        phase: str | None = None,
+    ) -> "_DirectConversation":
+        """Start a persistent multi-turn conversation session.
+
+        Returns a context manager with a `send(message) -> response` method.
+        Accumulates history and delegates each turn to invoke().
+
+        Usage:
+            with engine.conversation(persona=lead_dev, tools=False) as conv:
+                opening = conv.send("Introduce yourself")
+                response = conv.send(ceo_input)
+        """
+        return _DirectConversation(engine=self, persona=persona, kwargs=dict(
+            project_context=project_context,
+            tools=tools,
+            extra_tools=extra_tools,
+            model_override=model_override,
+            cancel_check=cancel_check,
+            phase=phase,
+        ))
+
+    def invoke(
+        self,
+        persona: Persona,
+        user_message: str,
+        project_context: str = "",
+        conversation_history: list[dict[str, Any]] | None = None,
+        tools: bool = True,
+        extra_tools: list[dict[str, Any]] | None = None,
+        max_tokens: int = DEFAULT_MAX_TOKENS,
+        model_override: str | None = None,
+        stream: StreamCallback | None = None,
+        cancel_check: Callable[[], bool] | None = None,
+        phase: str | None = None,
+        on_tool_result: Callable[[str, dict, str], None] | None = None,
+    ) -> str:
+        """Invoke an agent with strict persona isolation.
+
+        Builds the system prompt and conversation, then delegates to
+        DirectRunner.
+        """
+        # - Resolve stream callback --
+        if stream is None and self.default_stream_factory is not None:
+            stream = self.default_stream_factory(persona.name)
+
+        # - Debug stream logging --
+        if self.debug:
+            stream = _wrap_stream_debug(persona.name, stream)
+
+        # - Build system prompt --
+        has_tools = tools or bool(extra_tools)
+        base = self.working_dir or Path.cwd()
+        system = build_system_prompt(
+            persona, project_context, self.company_values,
+            tools=has_tools, working_dir=str(base),
+        )
+
+        # - Build messages --
+        messages = []
+        if conversation_history:
+            messages.extend(conversation_history)
+        messages.append({"role": "user", "content": user_message})
+
+        # - Resolve model --
+        model = model_override or persona.effective_model().value
+
+        # - Resolve tool definitions --
+        tool_defs: list[dict[str, Any]] | None = None
+        if tools or extra_tools:
+            td = list(TOOL_DEFINITIONS) if tools else []
+            if extra_tools:
+                td.extend(extra_tools)
+            if td:
+                tool_defs = td
+
+        # - Build shared middleware --
+        middleware = RunnerMiddleware(
+            cfo=self.cfo,
+            current_sprint=self.current_sprint,
+            phase=phase,
+        )
+
+        # - Delegate to runner --
+        runner = DirectRunner(
+            provider=self.provider,
+            escalations=self.escalations,
+            submissions=self.submissions,
+            working_dir=self.working_dir,
+        )
+        return runner.invoke(
+            persona,
+            system=system,
+            messages=messages,
+            tool_defs=tool_defs,
+            max_tokens=max_tokens,
+            model=model,
+            stream=stream,
+            cancel_check=cancel_check,
+            middleware=middleware,
+            on_tool_result=on_tool_result,
+        )
+
+
+class _DirectConversation:
+    """Multi-turn conversation wrapper.
+
+    Accumulates history and delegates each turn to engine.invoke().
+    """
+
+    def __init__(self, engine: AgentEngine, persona: Persona, kwargs: dict[str, Any]):
+        self._engine = engine
+        self._persona = persona
+        self._kwargs = kwargs
+        self._history: list[dict[str, Any]] = []
+        self.escalations: list[dict] = engine.escalations
+        self.submissions: list[dict] = engine.submissions
+
+    def open(self) -> None:
+        pass
+
+    def close(self) -> None:
+        pass
+
+    def __enter__(self) -> _DirectConversation:
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool:
+        return False
+
+    def send(self, user_message: str) -> str:
+        response = self._engine.invoke(
+            self._persona,
+            user_message=user_message,
+            conversation_history=list(self._history) if self._history else None,
+            **self._kwargs,
+        )
+        self._history.append({"role": "user", "content": user_message})
+        self._history.append({"role": "assistant", "content": response})
+        return response

odd/backlog.py

@@ -0,0 +1,117 @@
+"""Persistent backlog - work items that live across sprints.
+
+The CEO adds items, the lead dev prioritizes them into sprints.
+Items not completed in a sprint carry forward automatically.
+"""
+
+from __future__ import annotations
+
+import json
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from odd.config import BACKLOG_FILE, BACKLOG_ITEM_ID_PREFIX
+
+
+class Priority(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    NICE_TO_HAVE = "nice_to_have"
+
+
+class BacklogItem(BaseModel):
+    id: str
+    description: str
+    priority: Priority = Priority.MEDIUM
+    added_by: str = "CEO"  # who requested it
+    sprint_assigned: int | None = None  # which sprint picked it up
+    status: str = "open"  # open, in_sprint, done, cut
+    notes: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump()
+
+
+class Backlog:
+    """Persistent prioritized backlog stored in .odd/backlog.json."""
+
+    def __init__(self, odd_dir: Path):
+        self.path = odd_dir / BACKLOG_FILE
+        self._items: list[BacklogItem] = self._load()
+
+    def _load(self) -> list[BacklogItem]:
+        if not self.path.exists():
+            return []
+        data = json.loads(self.path.read_text(encoding="utf-8"))
+        return [BacklogItem(**item) for item in data]
+
+    def _save(self) -> None:
+        data = [item.to_dict() for item in self._items]
+        self.path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+    def save(self) -> None:
+        """Persist current backlog state to disk."""
+        self._save()
+
+    def add(self, description: str, priority: Priority = Priority.MEDIUM, added_by: str = "CEO") -> BacklogItem:
+        item_id = f"{BACKLOG_ITEM_ID_PREFIX}{len(self._items) + 1}"
+        item = BacklogItem(id=item_id, description=description, priority=priority, added_by=added_by)
+        self._items.append(item)
+        self._save()
+        return item
+
+    def assign_to_sprint(self, item_id: str, sprint_number: int) -> None:
+        item = self.get(item_id)
+        if item:
+            item.sprint_assigned = sprint_number
+            item.status = "in_sprint"
+            self._save()
+
+    def complete(self, item_id: str) -> None:
+        item = self.get(item_id)
+        if item:
+            item.status = "done"
+            self._save()
+
+    def cut(self, item_id: str) -> None:
+        """Cut an item - decided not to do it."""
+        item = self.get(item_id)
+        if item:
+            item.status = "cut"
+            self._save()
+
+    def get(self, item_id: str) -> BacklogItem | None:
+        for item in self._items:
+            if item.id == item_id:
+                return item
+        return None
+
+    def open_items(self) -> list[BacklogItem]:
+        return [i for i in self._items if i.status == "open"]
+
+    def sprint_items(self, sprint_number: int) -> list[BacklogItem]:
+        return [i for i in self._items if i.sprint_assigned == sprint_number]
+
+    def all_items(self) -> list[BacklogItem]:
+        return list(self._items)
+
+    def summary_for_agent(self) -> str:
+        """Produce a backlog summary for agent context."""
+        open_items = self.open_items()
+        if not open_items:
+            return "Backlog is empty."
+
+        priority_order = [Priority.CRITICAL, Priority.HIGH, Priority.MEDIUM, Priority.LOW, Priority.NICE_TO_HAVE]
+        lines = ["Current backlog:"]
+        for p in priority_order:
+            items = [i for i in open_items if i.priority == p]
+            if items:
+                lines.append(f"\n  [{p.value.upper()}]")
+                for item in items:
+                    lines.append(f"    {item.id}: {item.description}")
+        return "\n".join(lines)