kadmon 0.1.0__tar.gz

kadmon-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e '.[dev]'
+      - run: ruff check kadmon/ tests/
+      - run: pytest tests/ -v

kadmon-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish-pypi:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-npm:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+      - name: Sync version from tag
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          cd npm
+          npm version $VERSION --no-git-tag-version
+      - name: Publish with provenance
+        run: cd npm && npm publish --provenance --access public

kadmon-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.kadmon/
+*.db

kadmon-0.1.0/AGENTS.md

@@ -0,0 +1,111 @@
+# AGENTS.md
+
+Guidelines for AI agents contributing to this repository.
+
+## Build & Test Loop
+
+Every change must follow this cycle:
+
+1. **Understand** — Read relevant code before modifying. Use `grep_search` or `find_symbols` to locate what you need. Never guess at file contents.
+2. **Implement** — Make minimal, focused changes. One concern per edit.
+3. **Lint** — Run `ruff check kadmon/ tests/` and fix any issues.
+4. **Test** — Run `pytest tests/ -v`. All tests must pass. If you added new functionality, add tests for it.
+5. **Commit** — Use conventional commits (see below). Only commit when lint + tests pass.
+
+Do not skip steps. Do not commit broken code.
+
+## Development Setup
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Commands
+
+| Task | Command |
+|------|---------|
+| Lint | `ruff check kadmon/ tests/` |
+| Lint fix | `ruff check --fix kadmon/ tests/` |
+| Test | `pytest tests/ -v` |
+| Run agent | `kadmon run --task "..." --repo /path/to/repo` |
+| Run eval | `kadmon eval --dataset instances.json --limit 10` |
+
+## Commit Convention
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+type(scope): description
+```
+
+Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `ci`
+
+Scopes: `agent`, `tools`, `providers`, `eval`, `index`, `memory`, `cli`
+
+Examples:
+- `feat(tools): add grep_search with ripgrep fallback`
+- `fix(agent): prevent infinite loop on repeated tool errors`
+- `test(tools): add edit_file edge case coverage`
+- `docs: update README with eval instructions`
+
+Rules:
+- One logical change per commit
+- Implementation + its direct tests belong in the same commit
+- Keep commits atomic — each should build and pass tests independently
+- Never bundle unrelated changes
+
+## Code Style
+
+- Python 3.11+, type hints on all public functions
+- Use `pathlib.Path` for filesystem operations
+- Use dataclasses or pydantic models for structured data
+- Keep functions short (<40 lines). Extract helpers.
+- Error messages should be actionable (tell the user what to do next)
+- No `# type: ignore`, no `Any` unless unavoidable
+
+## Architecture Rules
+
+- **Tools** are the agent's interface to the world. Optimize tool output for LLM consumption (concise, structured, actionable errors).
+- **Providers** are stateless adapters. No business logic in providers.
+- **Agent loop** is single-threaded ReAct. Keep it simple.
+- **No frameworks** (no LangChain, no LangGraph). Use provider SDKs directly.
+- All paths resolved relative to `repo_root`. Validate path escaping.
+
+## Adding a New Tool
+
+1. Create `kadmon/tools/your_tool.py` with a class extending `Tool`
+2. Define `name`, `description`, `parameters` (JSON Schema)
+3. Implement `execute(**kwargs) -> ToolResult`
+4. Register in `kadmon/tools/__init__.py` inside `create_default_registry()`
+5. Add tests in `tests/test_tools.py`
+6. Run lint + tests before committing
+
+## Adding a New Provider
+
+1. Create `kadmon/providers/your_provider.py` implementing `LLMProvider` protocol
+2. Handle message format conversion (internal ↔ provider-specific)
+3. Add retry logic for transient errors
+4. Register in provider factory
+5. Add tests with mocked API responses
+
+## File Structure
+
+```
+kadmon/
+├── agent/       # Core loop, context management, planning
+├── providers/   # LLM provider implementations
+├── tools/       # Agent tools (file I/O, search, shell, etc.)
+├── eval/        # SWE-bench evaluation harness
+├── index/       # Tree-sitter symbol index (SQLite)
+├── memory/      # Cross-session memory and handoff
+└── cli.py       # CLI entry point
+```
+
+## What Not To Do
+
+- Don't add dependencies without justification
+- Don't add async unless the specific module requires it
+- Don't modify the core loop without understanding the full message flow
+- Don't delete or skip tests to make the build pass
+- Don't leave debug prints or commented-out code
+- Don't make changes outside the scope of your task

kadmon-0.1.0/LICENSE

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

kadmon-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: kadmon
+Version: 0.1.0
+Summary: An autonomous coding agent that manages its own context across sessions
+Project-URL: Homepage, https://github.com/ayuan153/kadmon
+Project-URL: Repository, https://github.com/ayuan153/kadmon
+Project-URL: Issues, https://github.com/ayuan153/kadmon/issues
+Author: ayuan153
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,autonomous,coding,llm
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: openai>=1.50.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tree-sitter-javascript>=0.23.0
+Requires-Dist: tree-sitter-python>=0.23.0
+Requires-Dist: tree-sitter-typescript>=0.23.0
+Requires-Dist: tree-sitter>=0.23.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Kadmon
+
+An autonomous coding agent that manages its own context, asks clarifying questions, and hands off between sessions without human intervention. Scores 100% on Aider Polyglot (Python) benchmark.
+
+## Install
+
+```bash
+pip install kadmon
+```
+
+## Getting Started
+
+```bash
+# Interactive setup — picks your provider, configures credentials, tests the connection
+kadmon init
+
+# Run on a repo
+cd your-project
+kadmon run --task "Fix the failing test in test_auth.py"
+```
+
+`kadmon init` walks you through:
+1. Choose provider (Bedrock, Anthropic, OpenAI)
+2. Configure credentials (AWS profile, API key, etc.)
+3. Test the connection
+4. Save to `.kadmon/config.toml`
+
+### Manual Provider Setup
+
+If you prefer to skip `kadmon init`:
+
+**AWS Bedrock** (default):
+```bash
+# Any standard AWS credential method works (SSO, env vars, profiles)
+export AWS_PROFILE=your-profile
+export AWS_REGION=us-east-1
+kadmon run --task "..." --provider bedrock --model us.anthropic.claude-sonnet-4-6
+```
+
+**Anthropic Direct**:
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+kadmon run --task "..." --provider anthropic --model claude-sonnet-4-20250514
+```
+
+**OpenAI**:
+```bash
+export OPENAI_API_KEY=sk-...
+kadmon run --task "..." --provider openai --model gpt-4o
+```
+
+## What Makes Kadmon Different
+
+Most coding agents are "very talented junior engineers" — they need constant supervision and context management. Kadmon is designed to be piloted like a **team lead manages a senior engineer**:
+
+1. **No guessing** — asks clarifying questions when requirements are ambiguous (not for permission — for correctness)
+2. **Rock climbing** — verifies each step before moving to the next, never sprints into the void
+3. **Self-managing context** — detects when its context is degrading, writes a handoff doc, and continues in a fresh session automatically
+
+### Autonomous Context Management
+
+```
+.kadmon/
+├── config.toml          # Provider config, preferences
+├── library/             # Persistent knowledge (survives across sessions)
+│   ├── architecture.md  # Project structure notes
+│   ├── conventions.md   # Patterns, gotchas
+│   └── tasks/current.md # Active task state
+├── session.json         # What's in flight right now
+├── handoffs/            # Handoff docs (context continuity)
+└── symbols.db           # Code structure index (tree-sitter)
+```
+
+The agent automatically:
+- Loads relevant library context on startup (cold start)
+- Saves learnings after each completed step
+- Detects context degradation (token budget, loops, quality drop)
+- Writes a structured handoff and resets — no human intervention needed
+
+## Local Development
+
+```bash
+# Clone and install in dev mode
+git clone https://github.com/ayuan153/kadmon.git
+cd kadmon
+pip install -e ".[dev]"
+
+# Run tests
+./dev test
+
+# Lint
+./dev lint
+
+# Run kadmon against a local repo
+./dev run "Fix the bug in parser.py"
+
+# Benchmark (5 Python exercises, quick smoke test)
+./dev bench
+
+# Full benchmark (225 exercises, all languages)
+./dev bench-full
+```
+
+### Dev Script Reference
+
+```bash
+./dev bench [N]     # N Python exercises (default: 5)
+./dev bench-full    # All 225 exercises, 6 languages
+./dev run "task"    # Run kadmon on current repo
+./dev test          # pytest
+./dev lint          # ruff
+```
+
+### Running Against Your Own Code
+
+```bash
+# From any repo:
+kadmon run --task "Add input validation to the create_user endpoint"
+
+# With planning disabled (faster, simpler loop — good for debugging):
+kadmon run --task "Fix the typo in README.md" --no-planning
+
+# In yolo mode (no tool approval gates):
+kadmon run --task "Refactor the auth module" --mode yolo
+```
+
+## Benchmarking
+
+### Aider Polyglot
+
+225 Exercism exercises across Python, JavaScript, Go, Rust, Java, C++.
+
+```bash
+# Quick smoke test (~$1)
+kadmon bench --languages python --limit 5
+
+# Full Python
+kadmon bench --languages python
+
+# All languages, 10 parallel workers
+kadmon bench -j 10
+
+# Sequential (live timer, good for debugging)
+kadmon bench --limit 5 -j 1
+```
+
+Results: `eval_results/polyglot/summary.json`
+
+### SWE-bench
+
+```bash
+kadmon eval --dataset swe_bench_verified_mini.json --limit 10
+```
+
+## Architecture
+
+```
+kadmon/
+├── agent/       # ReAct loop, planning, backtracking, handoff, pruner
+├── providers/   # LLM providers (Bedrock, Anthropic, OpenAI)
+├── tools/       # file I/O, search, shell, skeleton, references, plan, ask_human
+├── human/       # Question batching, CLI/webhook channels
+├── eval/        # Benchmark harnesses (Aider Polyglot, SWE-bench)
+├── index/       # Tree-sitter symbol index (SQLite)
+└── memory/      # Librarian, session tracker, read cache
+```
+
+Key design:
+- **Single-threaded ReAct loop** with architect/editor phase separation
+- **No frameworks** — provider SDKs directly, minimal core
+- **Autonomous handoff** — detects context degradation, resets with continuity
+- **File-based memory** — `.kadmon/library/` persists knowledge across sessions
+- **Ambiguity resolution** — `ask_human` tool for genuine uncertainty (not permission)
+
+## Configuration
+
+All defaults in `kadmon/config.py`:
+
+```python
+DEFAULT_MODEL = "us.anthropic.claude-sonnet-4-6"
+DEFAULT_PROVIDER = "bedrock"
+DEFAULT_REGION = "us-east-1"
+```
+
+Per-project config at `.kadmon/config.toml` (created by `kadmon init`).
+
+## Contributing
+
+See [AGENTS.md](AGENTS.md) for AI contribution guidelines. Key rules:
+- Build → Lint → Test → Commit (no skipping)
+- Conventional commits with scopes
+- One concern per commit
+
+## License
+
+MIT

kadmon-0.1.0/README.md

@@ -0,0 +1,196 @@
+# Kadmon
+
+An autonomous coding agent that manages its own context, asks clarifying questions, and hands off between sessions without human intervention. Scores 100% on Aider Polyglot (Python) benchmark.
+
+## Install
+
+```bash
+pip install kadmon
+```
+
+## Getting Started
+
+```bash
+# Interactive setup — picks your provider, configures credentials, tests the connection
+kadmon init
+
+# Run on a repo
+cd your-project
+kadmon run --task "Fix the failing test in test_auth.py"
+```
+
+`kadmon init` walks you through:
+1. Choose provider (Bedrock, Anthropic, OpenAI)
+2. Configure credentials (AWS profile, API key, etc.)
+3. Test the connection
+4. Save to `.kadmon/config.toml`
+
+### Manual Provider Setup
+
+If you prefer to skip `kadmon init`:
+
+**AWS Bedrock** (default):
+```bash
+# Any standard AWS credential method works (SSO, env vars, profiles)
+export AWS_PROFILE=your-profile
+export AWS_REGION=us-east-1
+kadmon run --task "..." --provider bedrock --model us.anthropic.claude-sonnet-4-6
+```
+
+**Anthropic Direct**:
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+kadmon run --task "..." --provider anthropic --model claude-sonnet-4-20250514
+```
+
+**OpenAI**:
+```bash
+export OPENAI_API_KEY=sk-...
+kadmon run --task "..." --provider openai --model gpt-4o
+```
+
+## What Makes Kadmon Different
+
+Most coding agents are "very talented junior engineers" — they need constant supervision and context management. Kadmon is designed to be piloted like a **team lead manages a senior engineer**:
+
+1. **No guessing** — asks clarifying questions when requirements are ambiguous (not for permission — for correctness)
+2. **Rock climbing** — verifies each step before moving to the next, never sprints into the void
+3. **Self-managing context** — detects when its context is degrading, writes a handoff doc, and continues in a fresh session automatically
+
+### Autonomous Context Management
+
+```
+.kadmon/
+├── config.toml          # Provider config, preferences
+├── library/             # Persistent knowledge (survives across sessions)
+│   ├── architecture.md  # Project structure notes
+│   ├── conventions.md   # Patterns, gotchas
+│   └── tasks/current.md # Active task state
+├── session.json         # What's in flight right now
+├── handoffs/            # Handoff docs (context continuity)
+└── symbols.db           # Code structure index (tree-sitter)
+```
+
+The agent automatically:
+- Loads relevant library context on startup (cold start)
+- Saves learnings after each completed step
+- Detects context degradation (token budget, loops, quality drop)
+- Writes a structured handoff and resets — no human intervention needed
+
+## Local Development
+
+```bash
+# Clone and install in dev mode
+git clone https://github.com/ayuan153/kadmon.git
+cd kadmon
+pip install -e ".[dev]"
+
+# Run tests
+./dev test
+
+# Lint
+./dev lint
+
+# Run kadmon against a local repo
+./dev run "Fix the bug in parser.py"
+
+# Benchmark (5 Python exercises, quick smoke test)
+./dev bench
+
+# Full benchmark (225 exercises, all languages)
+./dev bench-full
+```
+
+### Dev Script Reference
+
+```bash
+./dev bench [N]     # N Python exercises (default: 5)
+./dev bench-full    # All 225 exercises, 6 languages
+./dev run "task"    # Run kadmon on current repo
+./dev test          # pytest
+./dev lint          # ruff
+```
+
+### Running Against Your Own Code
+
+```bash
+# From any repo:
+kadmon run --task "Add input validation to the create_user endpoint"
+
+# With planning disabled (faster, simpler loop — good for debugging):
+kadmon run --task "Fix the typo in README.md" --no-planning
+
+# In yolo mode (no tool approval gates):
+kadmon run --task "Refactor the auth module" --mode yolo
+```
+
+## Benchmarking
+
+### Aider Polyglot
+
+225 Exercism exercises across Python, JavaScript, Go, Rust, Java, C++.
+
+```bash
+# Quick smoke test (~$1)
+kadmon bench --languages python --limit 5
+
+# Full Python
+kadmon bench --languages python
+
+# All languages, 10 parallel workers
+kadmon bench -j 10
+
+# Sequential (live timer, good for debugging)
+kadmon bench --limit 5 -j 1
+```
+
+Results: `eval_results/polyglot/summary.json`
+
+### SWE-bench
+
+```bash
+kadmon eval --dataset swe_bench_verified_mini.json --limit 10
+```
+
+## Architecture
+
+```
+kadmon/
+├── agent/       # ReAct loop, planning, backtracking, handoff, pruner
+├── providers/   # LLM providers (Bedrock, Anthropic, OpenAI)
+├── tools/       # file I/O, search, shell, skeleton, references, plan, ask_human
+├── human/       # Question batching, CLI/webhook channels
+├── eval/        # Benchmark harnesses (Aider Polyglot, SWE-bench)
+├── index/       # Tree-sitter symbol index (SQLite)
+└── memory/      # Librarian, session tracker, read cache
+```
+
+Key design:
+- **Single-threaded ReAct loop** with architect/editor phase separation
+- **No frameworks** — provider SDKs directly, minimal core
+- **Autonomous handoff** — detects context degradation, resets with continuity
+- **File-based memory** — `.kadmon/library/` persists knowledge across sessions
+- **Ambiguity resolution** — `ask_human` tool for genuine uncertainty (not permission)
+
+## Configuration
+
+All defaults in `kadmon/config.py`:
+
+```python
+DEFAULT_MODEL = "us.anthropic.claude-sonnet-4-6"
+DEFAULT_PROVIDER = "bedrock"
+DEFAULT_REGION = "us-east-1"
+```
+
+Per-project config at `.kadmon/config.toml` (created by `kadmon init`).
+
+## Contributing
+
+See [AGENTS.md](AGENTS.md) for AI contribution guidelines. Key rules:
+- Build → Lint → Test → Commit (no skipping)
+- Conventional commits with scopes
+- One concern per commit
+
+## License
+
+MIT

kadmon-0.1.0/dev

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Quick smoke test for kadmon using the 'kadmon' AWS profile.
+# Usage:
+#   ./dev bench              # 5 Python exercises (quick, ~$1)
+#   ./dev bench 20           # 20 Python exercises
+#   ./dev bench-full         # All 225 exercises (~$20)
+#   ./dev run "Fix the bug"  # Run on current repo
+#   ./dev test               # Run unit tests
+#   ./dev lint               # Run linter
+
+set -euo pipefail
+
+export AWS_PROFILE="${AWS_PROFILE:-kadmon}"
+export AWS_REGION="${AWS_REGION:-us-east-1}"
+MODEL="${KADMON_MODEL:-us.anthropic.claude-sonnet-4-6}"
+
+case "${1:-help}" in
+  bench)
+    LIMIT="${2:-5}"
+    echo "Running $LIMIT Python exercises (profile=$AWS_PROFILE model=$MODEL)"
+    kadmon bench --languages python --limit "$LIMIT" --provider bedrock \
+      --aws-region "$AWS_REGION" --model "$MODEL"
+    ;;
+  bench-full)
+    echo "Running full polyglot benchmark (225 exercises)"
+    kadmon bench --provider bedrock --aws-region "$AWS_REGION" --model "$MODEL"
+    ;;
+  run)
+    shift
+    kadmon run --task "$*" --repo . --provider bedrock \
+      --aws-region "$AWS_REGION" --model "$MODEL"
+    ;;
+  test)
+    pytest tests/ -v
+    ;;
+  lint)
+    ruff check kadmon/ tests/
+    ;;
+  help|*)
+    echo "Usage: ./dev <command>"
+    echo ""
+    echo "Commands:"
+    echo "  bench [N]       Run N Python exercises [default: 5]"
+    echo "  bench-full      Run all 225 exercises"
+    echo "  run \"task\"      Run kadmon on current repo"
+    echo "  test            Run unit tests"
+    echo "  lint            Run ruff linter"
+    echo ""
+    echo "Environment:"
+    echo "  AWS_PROFILE   AWS profile [default: kadmon]"
+    echo "  AWS_REGION    AWS region [default: us-east-1]"
+    echo "  KADMON_MODEL  Model ID [default: us.anthropic.claude-sonnet-4-6]"
+    ;;
+esac