coding-agents 0.0.1.dev0__py3-none-any.whl

coding_agents/verification/pipeline.py

@@ -0,0 +1,96 @@
+"""5-Stage progressive verification pipeline."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class StageResult:
+    stage_name: str
+    passed: bool
+    output: str
+    duration_seconds: float = 0.0
+    error_message: Optional[str] = None
+
+
+@dataclass
+class VerificationManifest:
+    all_passed: bool
+    stages: List[StageResult] = field(default_factory=list)
+    failed_stage: Optional[str] = None
+
+    @property
+    def summary(self) -> str:
+        status = "PASSED" if self.all_passed else f"FAILED at {self.failed_stage}"
+        return f"Verification {status} ({len(self.stages)} stages evaluated)"
+
+
+class VerificationPipeline:
+    """Progressive verification pipeline enforcing fast-fail semantics."""
+
+    def __init__(self, working_dir: str = ".") -> None:
+        self.working_dir = os.path.abspath(working_dir)
+
+    def run_stage_command(self, stage_name: str, cmd: str) -> StageResult:
+        try:
+            proc = subprocess.run(
+                cmd,
+                shell=True,
+                cwd=self.working_dir,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+                timeout=120,
+            )
+            passed = (proc.returncode == 0)
+            return StageResult(
+                stage_name=stage_name,
+                passed=passed,
+                output=proc.stdout,
+                error_message=None if passed else f"Exit code {proc.returncode}",
+            )
+        except Exception as e:
+            return StageResult(
+                stage_name=stage_name,
+                passed=False,
+                output="",
+                error_message=str(e),
+            )
+
+    def verify_syntax(self, target_dir: str = ".") -> StageResult:
+        """Stage 1: Fast AST syntax compilation (<1s)."""
+        cmd = f"python -m compileall -q {target_dir}"
+        return self.run_stage_command("Stage 1: Syntax / Compilation", cmd)
+
+    def verify_tests(self, test_path: str = "tests/") -> StageResult:
+        """Stage 2: Unit test suite."""
+        cmd = f"pytest -q {test_path}"
+        return self.run_stage_command("Stage 2: Unit Tests", cmd)
+
+    def run_all(self, target_dir: str = ".", test_path: str = "tests/") -> VerificationManifest:
+        """Run all stages in progressive order, stopping on the first failure."""
+        manifest = VerificationManifest(all_passed=True)
+
+        # Stage 1: Syntax
+        s1 = self.verify_syntax(target_dir)
+        manifest.stages.append(s1)
+        if not s1.passed:
+            manifest.all_passed = False
+            manifest.failed_stage = s1.stage_name
+            return manifest
+
+        # Stage 2: Unit tests
+        if os.path.exists(os.path.join(self.working_dir, test_path)):
+            s2 = self.verify_tests(test_path)
+            manifest.stages.append(s2)
+            if not s2.passed:
+                manifest.all_passed = False
+                manifest.failed_stage = s2.stage_name
+                return manifest
+
+        return manifest
+

coding_agents-0.0.1.dev0.dist-info/METADATA

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: coding-agents
+Version: 0.0.1.dev0
+Summary: The reference software engineering harness and runtime for autonomous coding agents.
+Author-email: Coding Agents Authors <authors@example.com>
+License: MIT
+Keywords: coding-agents,llm-agents,software-engineering,harness,autonomous-coding,swe-bench
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.20.0; extra == "llm"
+Requires-Dist: openai>=1.0.0; extra == "llm"
+
+# Coding Agents: Foundations, Architecture, Harnesses, and Enterprise Practice
+
+*Building, Orchestrating, Evaluating, and Scaling AI Software Engineers*
+
+A Peanutbook manuscript. Build it with `bubble-build`; read the source in
+`chapter*/`.
+
+---
+
+## What this book argues
+
+One claim, stated in Chapter 1 and earned over the following eleven:
+
+> **A coding agent is not a language model with a code prompt. It is a software
+> engineering system built around a model.**
+
+The question it answers is not whether AI can write code. That is settled, and
+settling it mattered less than everyone expected. The question is:
+
+> **How do we engineer software-development systems in which humans and coding
+> agents work together reliably on large production codebases?**
+
+Roughly seventy percent of the text is architecture, large-codebase practice,
+verification, evaluation, security, and multi-agent engineering. The other
+thirty percent uses specific systems as concrete implementations, because
+abstract discussion of agents is unfalsifiable and boring. That ratio is
+deliberate: the named products will be replaced, some of them before this is in
+print. The questions in the other seventy percent will not.
+
+---
+
+## Register
+
+The voice is already set by the first three chapters. Match it. These are
+descriptions of what the existing prose does, not aspirations.
+
+**Address the reader as "you." Never "we."** Across the written chapters: 89
+instances of *you*, one of *we*. The reader is an engineer doing this work, not
+a co-author being carried along.
+
+**First person singular is rationed, and only ever for first-hand experience.**
+Four instances in fifteen thousand words, all of the form *"in notes I wrote in
+March 2024."* Use it to introduce evidence you personally hold. Never for
+opinion — the argument should stand without the byline.
+
+**State the claim, then earn it.** The paragraph shape is: assertion,
+mechanism, consequence. Not: build-up, build-up, reveal.
+
+**Prefer the corrective construction.** *X is not Y. It is Z.* — "The context
+window is not storage. It is a working set." "File context is not repository
+context." This is the book's most characteristic sentence, because most of what
+it has to teach is a correction to a reasonable-sounding wrong model.
+
+**End on the consequence, not the hedge.** A sentence that trails off into
+*"...but of course this depends on your situation"* has wasted the reader's
+attention. If it depends, say what it depends on.
+
+**No hype vocabulary.** No *revolutionary*, *seamless*, *game-changing*,
+*paradigm shift*, *cutting-edge*. The existing chapters contain none. Enthusiasm
+is conveyed by precision, not adjectives.
+
+**Concrete over abstract, always.** A number with a date beats a
+characterization. A named failure beats "challenges." A worked example beats a
+principle.
+
+**Date every number, or state only the shape.** The field moves fast enough that
+an undated figure is worse than none, and a book that quotes a leaderboard
+without saying when looks careless within a year. Where a figure carries an
+argument, cite the paper and the date. Where only the trend matters, describe
+the trend.
+
+**Name few products, and never rank them.** A book that ranks models has a shelf
+life measured in months.
+
+**Say what did not work.** Anyone can write "here are the best practices." The
+material worth reading is *"we thought the bottleneck was X and it was Y."* The
+author's own failed work is the strongest evidence in the book; use it.
+
+**Admit uncertainty in the text, not in a hedge.** "This is model-specific and
+worth measuring on your own workload" is honest. "This may or may not apply" is
+noise.
+
+### Structural habits
+
+| Element | Convention |
+| :--- | :--- |
+| `>IMPORS:` box | One claim, stated once. About six per chapter. |
+| `>NOTES:` box | An aside the reader can skip. About two per chapter. |
+| Cross-references | Constant — roughly one per 230 words. Every chapter says which chapter takes a thread further. |
+| Figure captions | 20 words maximum, stating the claim. Longer explanation goes in the paragraph that introduces the figure. |
+| `<!-- -->` comments | Author notes, verification lists, publication gates. Dropped from the PDF. |
+| Chapter ending | A named handoff to the next chapter. |
+
+### Two things that are not register, but read like it
+
+**`>NOTES:` blocks print.** They are for the reader. Notes to yourself go in
+HTML comments, which pandoc drops.
+
+**Every chapter opens with a real, attributed epigraph.** Brooks (Ch 1), Parnas
+(Ch 2), Pike (Ch 3). Do not invent quotes, and do not attribute the book's own
+theses to anyone — those belong in `>IMPORS:` boxes.
+
+---
+
+## Shelf life
+
+The book is written for a **5–10 year spine and a 2–3 year surface**, and the
+two need to stay physically separable.
+
+What is being bet on lasting: the verification principle, context as a working
+set with an allocator, file context against repository context, benchmarks
+scoring a harness rather than a model, paired evaluation, the prefill/decode
+asymmetry, and the seven-component decomposition — which survives on Parnas's
+test, not on fashion, because each component is a decision that changes
+independently of the others.
+
+What will rot on schedule: model names, context sizes, prices, benchmark
+numbers, API shapes, and the current claim that frontier general models beat
+code-only models. All of it is real and all of it belongs in the book.
+
+This ships on KDP, where a revised interior is a re-upload rather than a print
+run, so the cost of carrying perishable material is low and the book can afford
+more of it than a traditionally published one. But **the thing that does not get
+revised is the reviews.** A one-star "already out of date" from the first
+edition sits on the same product page as the fourth, and no amount of iteration
+removes it. So perishable content is still quarantined into clearly dated
+sections — not to make revision cheap, but because a reader forgives datedness
+they were warned about and punishes datedness that presented itself as current.
+
+Handled that way the perishable sections invert from liability to asset: a
+section titled *The Frontier, as of <month year>* is a reason to buy the new
+edition. Put the edition and its date on the title page, and keep a short
+revision record in the back matter.
+
+The genuine risk is not that details age. It is that the **harness framing
+itself** gets absorbed — models that do multi-hour repository work with no
+scaffold would turn Part II into a historical chapter. The hedge is to write the
+harness chapters around *why* a harness exists — verification, budget, policy,
+accountability — rather than *how to build one*. Those four survive the
+absorption, because someone still has to verify the diff, pay for it, constrain
+it, and answer for it.
+
+The lifespan is therefore mostly decided by whether the book's own concepts get
+adopted: the Coding Agent Stack, the Evolution Ladder, the Agent-Ready
+Repository, Harness Engineering. A book that is cited for its framework outlives
+its examples. A book that only summarizes today's tools does not, however well
+written.
+
+---
+
+## Structure
+
+Four parts, twelve chapters, following one line of development:
+
+```text
+Static Agent -> Stateful -> Persistent -> Multi-Agent -> Self-Evolving
+```
+
+| # | Chapter | Words | State |
+| ---: | :--- | ---: | :--- |
+| | **Part I — Foundations** | | |
+| 1 | Code Language Models | 4,300 | drafted |
+| 2 | Anatomy of a Coding Agent | 6,200 | drafted |
+| 3 | Context and Repository Understanding | 4,100 | drafted |
+| | **Part II — The Agent Harness** | | |
+| 4 | Tools, Skills, and Agent Harnesses | 4,700 | drafted |
+| 5 | Planning and Spec-Driven Development | 4,600 | drafted |
+| 6 | Coding, Debugging, and Refactoring | 4,500 | drafted |
+| 7 | Verification and Repair | | outline |
+| | **Part III — Coding Agents in Production** | | |
+| 8 | Coding Agents at Scale | | outline |
+| 9 | Long-Running and Multi-Agent Systems | | outline |
+| 10 | Evaluation, Observability, and Economics | | outline |
+| 11 | Security and Enterprise Deployment | | outline |
+| | **Part IV — The Next Generation** | | |
+| 12 | Self-Evolving Coding Agents | | outline |
+
+Front matter is in `chapterx/` — the preface is outlined, not written, and it
+owns the author-credibility argument and the book-structure walkthrough.
+`chapter2/_draft-from-ch1.md` is the original Chapter 1, kept because its
+forty-line agent and enterprise retrospective still have somewhere to go.
+
+The concepts the book has to deliver, not merely name: the **Coding Agent
+Stack**, the **Agentic Software Engineering Loop**, the **Agent-Ready
+Repository** and its readiness score, **Harness Engineering**, and the **Coding
+Agent Evolution Ladder**.
+
+---
+
+## Building
+
+```bash
+conda activate usao
+
+bubble-convert 3              # one chapter, while drafting
+bubble-build --style square   # the whole book -> book_square.pdf
+bubble-single-star            # style lint
+```
+
+`bubble-convert` does **not** run figure scripts; only `bubble-build` does. When
+you change a figure while drafting, run it yourself first:
+
+```bash
+cd chapter3-*/img && python myfig.py && cd ../..
+```
+
+Check captions before building:
+
+```bash
+grep -rn '^!\[' chapter*/*.md | sed 's/^\(.*\):!\[\(.*\)\](.*/\1|\2/' \
+  | awk -F'|' '{n=split($2,a," "); if (n>20) printf "%d words: %s\n", n, $1}'
+```
+
+Figures are generated by Python scripts in each chapter's `img/`, never
+committed as hand-made images. The conventions are in
+`.claude/skills/peanutbook-figures/`; mindmaps need `mathicon`.
+
+---
+
+## Source material, and the gate on it
+
+`raw/` holds the author's Oracle talk and design notes from 2023–2024. Read
+`raw/README.md` before using any of it.
+
+The short version: the model rankings in those notes are dead, and the methods
+are not. The recitation probe, paired evaluation, and the generate–verify–repair
+loop all come from there and all still hold. Cite the papers with dates, never
+the slides. Abstract employer-internal specifics into general lessons, strip
+colleague names and email addresses, and confirm publication clearance.
+
+---
+
+## Before this ships
+
+- [ ] Preface written — it owns the author's position and the book's structure
+- [ ] Every date, benchmark size, and figure verified against its source
+- [ ] The frontier claims in Chapter 1 re-checked and stamped
+- [ ] `author` set in `peanut.config`; covers replaced
+- [ ] Every `@fig:` resolves, no caption over 20 words, `bubble-single-star` clean

coding_agents-0.0.1.dev0.dist-info/RECORD

@@ -0,0 +1,27 @@
+coding_agents/__init__.py,sha256=rkRB23fBxpF6dLbT8QynQ9KpL1q86i5vW-4E8ENpykY,1262
+coding_agents/cli.py,sha256=MJbXXtYfG4Yvghcmp82w95VsexEf3UXe7SG4AqdQqZg,3766
+coding_agents/py.typed,sha256=vx7tBj6kTigcpvoMSNBQg7evqJ8tdCbVHEFiPbiFOKo,40
+coding_agents/core/__init__.py,sha256=KHgAhEpxujSl_Vq3G3C_vf2GSbtDzugL8_qMwmqkHqs,576
+coding_agents/core/agent.py,sha256=IsMhz01q1GGho23AmHtKUwvYIyoeX8MIOhzFJwwUmI8,5962
+coding_agents/core/budget.py,sha256=zfoFvH_dk1js69NdmdQJ6LqQl0Rrzcw2qBnsBTjltbU,2587
+coding_agents/core/loop.py,sha256=1fQTrzweQyBcMLatHil3HOL3z3YCU2TxnD6JW8aqfdk,2731
+coding_agents/core/models.py,sha256=MK89CnnojkdnAGfUzGmf-l4xIWYImNtTA4YBYAwH2tI,2983
+coding_agents/evolution/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+coding_agents/evolution/parallel_planner.py,sha256=6Qmz90GPK1sSxwxKTojNzkBd8t8_KFFyP8mBA82waUQ,2213
+coding_agents/evolution/skill_miner.py,sha256=UZTftp0VPIXdRon3Xhn3ugKuxNWiTTDaUTTMZFBWk4Y,3692
+coding_agents/sandbox/__init__.py,sha256=Rwb67i2jRrQA_dzO1GJJaRAckRxgyVNg-l5x6oSpOEU,203
+coding_agents/sandbox/policy.py,sha256=pbKnnFJZLba8ZKC1iHAcU6rK0cs_Xe21Gd7cQo0YeUs,2154
+coding_agents/sandbox/worktree.py,sha256=FpyQ3nbCmJUDvJhXQl6J-vAJN9WTvZK3RBH0zc4acQA,2058
+coding_agents/tools/__init__.py,sha256=HVTEcclExEzMlKdB1u6MRbTTn6dzooB7697dzi-tRRU,260
+coding_agents/tools/base.py,sha256=IUeqViFkNPWug_28igsqPVhyqXp6btbY_YdvOSGMPyU,1510
+coding_agents/tools/bash_tool.py,sha256=3J_pvAaGDT2zNzD-NL9_ErPaq7m3Pb7pxVlvuVH6IuY,3332
+coding_agents/tools/patch_editor.py,sha256=jQdHOUI82qKOCqbUxTmlcqakSH4wu00aFKaAKF8aPzg,3673
+coding_agents/verification/__init__.py,sha256=zgYClSkvPKtJ6o3FntNFSaqypFuJbKMaaRqTzMpW67Y,497
+coding_agents/verification/fault_localizer.py,sha256=nH-mKI4YLluu4McKxIJxRxl6CzXs_bztv1-JOffHWeo,1902
+coding_agents/verification/oscillation.py,sha256=5cCrtZgUoHhJNzyLzJRJ061UlJqEm-DWCYWWsa9_1mU,1694
+coding_agents/verification/pipeline.py,sha256=17_VR204Va5diNaXlBX8kcYcLSkL33W-Wa9zxvBKVjA,3116
+coding_agents-0.0.1.dev0.dist-info/METADATA,sha256=qiGGxsRnV1yrqGgGmzFVyiPTjvQLXuljudhdwnMdXu8,11675
+coding_agents-0.0.1.dev0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+coding_agents-0.0.1.dev0.dist-info/entry_points.txt,sha256=WXzy8PQRVJ7WOEHo1DDzVGUO9g7_5EzdTGTDmzPlFTA,56
+coding_agents-0.0.1.dev0.dist-info/top_level.txt,sha256=HYiwX7hSgCfcr9Kq0w3fvRPuvlXKTVskapcum5ChibM,14
+coding_agents-0.0.1.dev0.dist-info/RECORD,,

coding_agents-0.0.1.dev0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

coding_agents-0.0.1.dev0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+coding-agent = coding_agents.cli:main

coding_agents-0.0.1.dev0.dist-info/top_level.txt

@@ -0,0 +1 @@
+coding_agents