dfm-agent 0.0.1__tar.gz

dfm_agent-0.0.1/.gitignore

@@ -0,0 +1,19 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.pyright/
+dist/
+build/
+*.egg-info/
+.dfm/
+.DS_Store
+
+# Local working files: the development log and agent working notes stay on this machine
+BUILD_STATE.md
+HANDOVER.md
+MASTER_PROMPT.md
+issues/
+docs/upstream/
+docs/milestones/

dfm_agent-0.0.1/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning:
+[Semantic Versioning](https://semver.org/); before 1.0, any release may contain breaking changes.
+
+## [Unreleased]
+
+### Fixed
+
+- On Python 3.12, a command that left a background process holding its output (for example a
+  test run that starts a daemon) blocked until its timeout. DFM now reads output pipes itself,
+  so it stops waiting when the command exits on every supported Python version.
+- Type checking failed without the optional `mlx` extra.
+- A versioned Xcode install (`/Applications/Xcode_16.4.app`, as on CI runners and machines
+  with several Xcodes) was treated as outside the repository boundary, so policy refused
+  `swift test` with the Swift Testing plugin path.
+- Service and Docker availability checks looked up binaries on DFM's own `PATH` rather than
+  the one the command then runs with.
+- The configuration reference split rows whose type contains `|` (such as `int | None`).
+- A diagram in `ARCHITECTURE.md` did not render on GitHub.
+
+### Changed
+
+- Live model tests are opt-in through `DFM_TEST_MODEL` and work with any local MLX model, not
+  only gpt-oss-20b. Model-logic tests no longer depend on whether `mlx` is installed.
+- CI runs on Python 3.12 and 3.13, with actions pinned to commit SHAs.
+- The package is distributed as `dfm-agent` (the command stays `dfm`); install with
+  `uv tool install "dfm-agent[mlx]"`. RepoCanon and RepoKG are released dependencies with
+  version bounds instead of pinned Git commits, the sdist contains only what the package ships,
+  and a tag push publishes to PyPI through trusted publishing (ADR 0014).
+
+## [0.0.1]
+
+First public release.
+
+### Added
+
+- Commands: `ask`, `plan`, `implement` (optionally in a worktree), `resume`, `review`,
+  `security-review`, `ci`, `fix-pr`, `review-pr`, `implement-issue`, `issue`, `pr`, `comments`,
+  `benchmark`, `doctor`, `setup`, `models`, `repo`, `diff`, `inspect-log`, `sessions`, `status`,
+  `profile`, `processes`, `services`, `memory`, `config`.
+- On-device models: Apple FM through the `fm` CLI, and MLX models in a sandboxed worker process,
+  behind one interface with fallback and circuit breakers.
+- Deterministic routing with an Apple FM tie-breaker and memory-aware model selection.
+- Agent loop: one action per step, native tool calls, per-step reasoning effort, thinking and
+  task token budgets, history compaction, repair, and a verification ledger.
+- Safeguards: command classifier, policy engine with typed confirmations, per-command macOS
+  sandbox, secret redaction, prompt-injection handling, Git guard and hardening, filesystem
+  boundary with checkpoints.
+- Resource controls: memory admission, thermal pacing, loop cutoff, and a KV cache reused across
+  steps and sessions.
+- Integrations: RepoCanon, RepoKG, Reflex, GitHub (`gh`), Docker and Compose, Kubernetes, LSP.
+  Language support: Python, TypeScript, Rust, Go, Swift, Solidity, Cairo.
+- Versioned JSONL session traces, checkpoints and recovery, per-session metrics.
+- Documentation: guide, architecture, command and configuration references, policy, threat
+  model, troubleshooting, ADRs 0001–0013.

dfm_agent-0.0.1/LICENSE

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

dfm_agent-0.0.1/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: dfm-agent
+Version: 0.0.1
+Summary: Developer Foundation Model: a local, privacy-first engineering agent for Apple Silicon.
+Project-URL: Homepage, https://github.com/NehharShah/dfm
+Project-URL: Documentation, https://github.com/NehharShah/dfm/blob/main/docs/guide.md
+Project-URL: Issues, https://github.com/NehharShah/dfm/issues
+Project-URL: Changelog, https://github.com/NehharShah/dfm/blob/main/CHANGELOG.md
+Author: Nihar Shah
+License: MIT
+License-File: LICENSE
+Keywords: apple-silicon,coding-agent,developer-tools,local-llm,mlx,privacy
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: repocanon<0.3,>=0.2.1
+Requires-Dist: repokg<0.5,>=0.4.5
+Requires-Dist: rich>=13.7.1
+Requires-Dist: typer>=0.12.3
+Provides-Extra: mlx
+Requires-Dist: mlx-lm>=0.32.2; extra == 'mlx'
+Description-Content-Type: text/markdown
+
+# dfm — Developer Foundation Model
+
+[![CI](https://github.com/NehharShah/dfm/actions/workflows/ci.yml/badge.svg)](https://github.com/NehharShah/dfm/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Platform: macOS on Apple Silicon](https://img.shields.io/badge/platform-macOS%20Apple%20Silicon-lightgrey)
+![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)
+
+A coding agent that runs entirely on your Mac. DFM edits, builds, tests, repairs and verifies
+code using on-device models: Apple FM for routing and short text, and a local MLX model for
+code. Repository knowledge comes from [RepoCanon](https://github.com/NehharShah/repocanon),
+[RepoKG](https://github.com/NehharShah/repokg) and, optionally,
+[Reflex](https://github.com/sumervaid/reflex-tui).
+
+DFM sends no code or prompts to hosted models. Other network access (GitHub, package registries)
+is off or requires approval, per [policy](docs/policy.md).
+
+**Status:** early (0.0.1). Commands and configuration may change.
+
+## Requirements
+
+- macOS on Apple Silicon, Python 3.12+, [uv](https://docs.astral.sh/uv/), Git.
+- Memory for the local model: the recommended 27B model (4-bit) needs about 18.5 GB at its
+  default context, so 32 GB or more is recommended. `dfm setup` picks a model that fits.
+- Optional: Apple Intelligence, for Apple FM.
+
+## Quick start
+
+Install `dfm` as a command (the package is `dfm-agent`; the command is `dfm`):
+
+```bash
+uv tool install "dfm-agent[mlx]"           # from PyPI, once released
+uv tool install "git+https://github.com/NehharShah/dfm[mlx]"   # or straight from GitHub
+dfm doctor                                 # check this machine
+dfm setup                                  # choose a local model
+dfm implement "fix the failing test"
+```
+
+Omit `[mlx]` to install without the local coder. Upgrade with `uv tool upgrade dfm-agent`.
+To run from a checkout instead, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## How it works
+
+- The model proposes one action at a time (read, search, patch, run, test). DFM executes it,
+  reruns the tests after every edit, and reports only what a command verified.
+- Every command is classified and checked against policy, then runs in a per-command macOS
+  sandbox. Destructive, production and mainnet actions require a typed confirmation. DFM does
+  not commit, push or rewrite history.
+- Repository files, issues and CI logs reach the model as untrusted data, with secrets
+  redacted.
+- Memory checks, thermal pacing, reasoning budgets and a persistent prompt cache keep the model
+  usable alongside other apps.
+
+Modes: `ask`, `plan`, `implement`, `review`, `security-review`, `ci`, `fix-pr`,
+`implement-issue`, `benchmark`. Full list: [command reference](docs/cli.md).
+
+## Documentation
+
+[Guide](docs/guide.md) · [Architecture](ARCHITECTURE.md) · [Commands](docs/cli.md) ·
+[Configuration](docs/config.md) · [Policy](docs/policy.md) · [Threat model](docs/threat-model.md) ·
+[Troubleshooting](docs/troubleshooting.md) · [Design decisions](docs/decisions)
+
+## Contributing and security
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md). Report vulnerabilities
+privately as described in [SECURITY.md](SECURITY.md). Changes: [CHANGELOG.md](CHANGELOG.md).
+
+## License and notices
+
+DFM is released under the [MIT License](LICENSE) and is provided "as is", without warranty of
+any kind. DFM runs commands and changes files on your machine. Its safeguards reduce risk but do
+not eliminate it. Review its changes before you commit them.
+
+Models are third-party software under their own licenses, and you are responsible for complying
+with the license of any model you download. RepoCanon, RepoKG and Reflex are separate projects
+under their own licenses.
+
+Apple, Apple Intelligence, Apple Silicon and macOS are trademarks of Apple Inc. DFM is an
+independent project and is not affiliated with or endorsed by Apple.

dfm_agent-0.0.1/README.md

@@ -0,0 +1,78 @@
+# dfm — Developer Foundation Model
+
+[![CI](https://github.com/NehharShah/dfm/actions/workflows/ci.yml/badge.svg)](https://github.com/NehharShah/dfm/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Platform: macOS on Apple Silicon](https://img.shields.io/badge/platform-macOS%20Apple%20Silicon-lightgrey)
+![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)
+
+A coding agent that runs entirely on your Mac. DFM edits, builds, tests, repairs and verifies
+code using on-device models: Apple FM for routing and short text, and a local MLX model for
+code. Repository knowledge comes from [RepoCanon](https://github.com/NehharShah/repocanon),
+[RepoKG](https://github.com/NehharShah/repokg) and, optionally,
+[Reflex](https://github.com/sumervaid/reflex-tui).
+
+DFM sends no code or prompts to hosted models. Other network access (GitHub, package registries)
+is off or requires approval, per [policy](docs/policy.md).
+
+**Status:** early (0.0.1). Commands and configuration may change.
+
+## Requirements
+
+- macOS on Apple Silicon, Python 3.12+, [uv](https://docs.astral.sh/uv/), Git.
+- Memory for the local model: the recommended 27B model (4-bit) needs about 18.5 GB at its
+  default context, so 32 GB or more is recommended. `dfm setup` picks a model that fits.
+- Optional: Apple Intelligence, for Apple FM.
+
+## Quick start
+
+Install `dfm` as a command (the package is `dfm-agent`; the command is `dfm`):
+
+```bash
+uv tool install "dfm-agent[mlx]"           # from PyPI, once released
+uv tool install "git+https://github.com/NehharShah/dfm[mlx]"   # or straight from GitHub
+dfm doctor                                 # check this machine
+dfm setup                                  # choose a local model
+dfm implement "fix the failing test"
+```
+
+Omit `[mlx]` to install without the local coder. Upgrade with `uv tool upgrade dfm-agent`.
+To run from a checkout instead, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## How it works
+
+- The model proposes one action at a time (read, search, patch, run, test). DFM executes it,
+  reruns the tests after every edit, and reports only what a command verified.
+- Every command is classified and checked against policy, then runs in a per-command macOS
+  sandbox. Destructive, production and mainnet actions require a typed confirmation. DFM does
+  not commit, push or rewrite history.
+- Repository files, issues and CI logs reach the model as untrusted data, with secrets
+  redacted.
+- Memory checks, thermal pacing, reasoning budgets and a persistent prompt cache keep the model
+  usable alongside other apps.
+
+Modes: `ask`, `plan`, `implement`, `review`, `security-review`, `ci`, `fix-pr`,
+`implement-issue`, `benchmark`. Full list: [command reference](docs/cli.md).
+
+## Documentation
+
+[Guide](docs/guide.md) · [Architecture](ARCHITECTURE.md) · [Commands](docs/cli.md) ·
+[Configuration](docs/config.md) · [Policy](docs/policy.md) · [Threat model](docs/threat-model.md) ·
+[Troubleshooting](docs/troubleshooting.md) · [Design decisions](docs/decisions)
+
+## Contributing and security
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md). Report vulnerabilities
+privately as described in [SECURITY.md](SECURITY.md). Changes: [CHANGELOG.md](CHANGELOG.md).
+
+## License and notices
+
+DFM is released under the [MIT License](LICENSE) and is provided "as is", without warranty of
+any kind. DFM runs commands and changes files on your machine. Its safeguards reduce risk but do
+not eliminate it. Review its changes before you commit them.
+
+Models are third-party software under their own licenses, and you are responsible for complying
+with the license of any model you download. RepoCanon, RepoKG and Reflex are separate projects
+under their own licenses.
+
+Apple, Apple Intelligence, Apple Silicon and macOS are trademarks of Apple Inc. DFM is an
+independent project and is not affiliated with or endorsed by Apple.

dfm_agent-0.0.1/SECURITY.md

@@ -0,0 +1,43 @@
+# Security policy
+
+DFM runs repository code and acts on proposals from a local model, which can be manipulated by
+the content it reads. A way around its safeguards (policy, command classifier, sandbox, secret
+redaction or Git guard) is a vulnerability. The threats DFM is designed against are listed in
+[docs/threat-model.md](docs/threat-model.md).
+
+## Reporting
+
+Report vulnerabilities privately through a
+[GitHub security advisory](https://github.com/NehharShah/dfm/security/advisories/new). Do not open
+a public issue.
+
+Include:
+
+- the command or a minimal repository that reproduces the issue;
+- what DFM did and what you expected;
+- `dfm --version`, the macOS version and the chip.
+
+We aim to acknowledge reports within 7 days. Confirmed issues are fixed with a regression test
+in the threat suite (`pytest -m threat`). With your consent, we credit you in the changelog.
+Please allow a reasonable time for a fix before you disclose publicly.
+
+## In scope
+
+- A command that runs without the approval its policy requires.
+- Reading protected paths, writing outside allowed paths, or reaching the network from inside
+  the sandbox without approval.
+- Secrets reaching model context, session traces, logs or approval prompts.
+- Repository content, issues, CI logs or tool output changing DFM's policy or configuration.
+- DFM overwriting uncommitted work, pushing, or rewriting history without being asked.
+- Any request to a hosted model.
+
+## Out of scope
+
+- Actions you approved, or allowed in your own configuration.
+- The behaviour of code you asked DFM to run, within the sandbox's limits.
+- Weaknesses in macOS or `sandbox-exec` itself, and running DFM without the sandbox.
+- Vulnerabilities in RepoCanon, RepoKG or Reflex. Report those to their own projects.
+
+## Supported versions
+
+Only the latest commit on `main` receives security fixes while DFM is at 0.x.

dfm_agent-0.0.1/dfm/__init__.py

@@ -0,0 +1,10 @@
+"""DFM — Developer Foundation Model: a local, privacy-first engineering agent."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("dfm-agent")  # the distribution; the package and command are `dfm`
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

dfm_agent-0.0.1/dfm/benchmark/__init__.py

@@ -0,0 +1,25 @@
+"""`dfm benchmark`: ablation benchmarks over fixture tasks."""
+
+from dfm.benchmark.runner import (
+    ABLATIONS,
+    ReferenceCoder,
+    RunResult,
+    run_suite,
+    run_task,
+    table,
+    write_results,
+)
+from dfm.benchmark.tasks import BY_ID, TASKS, BenchTask
+
+__all__ = [
+    "ABLATIONS",
+    "BY_ID",
+    "TASKS",
+    "BenchTask",
+    "ReferenceCoder",
+    "RunResult",
+    "run_suite",
+    "run_task",
+    "table",
+    "write_results",
+]