Feat llm dev - #1
Open
SofiaBillBerg wants to merge 18 commits into
Open
Conversation
Run 'pre-push' to automatically run format and lint check with 'project_management/run_formatters.sh' - write results to ‘.code_quality_outputs’ (where analysis have been performed, else edit in-place)., and generate class diagrams automatically for each class in ‘code_agent’. Write to ‘docs/visualization’
Integrates the full worktree branch into feat-llm-dev: - config refactor: code_agent/settings.py (pydantic_settings), .env.example, env-based config loading, delete obsolete code_agent/config/llm_config.json - capabilities subsystem (audit/envelope/registry/tool_adapter) - provider, cli, main, webapp and docs updates - tests: test_capabilities, test_ui, test_web, etc. Excludes node_modules and gitignored bookkeeping.
…xports - Add exclusion patterns in `.gitignore` including `.*`, and temporary directories to prevent leaking generated artifacts or logs. - Reorder public API imports in `code_agent/__init__.py` by moving exceptions earlier and formatting multi-line lists consistently across sub-package init files. - Remove obsolete diagram visualization references from the documentation section in `docs/API.qmd`.
…pace formatting across modules - Group exception classes above utility functions in `code_agent/__init__.py` to clarify public API surface ordering logic and separate errors from providers - Strip trailing blank lines from provider implementations, UI handlers, and test files to align with strict whitespace enforcement rules for consistent linter compliance - Remove obsolete image markdown reference from `docs/API.qmd` to fix documentation consistency for the generated web interface
…re patterns - Reorder Python imports across multiple test modules to consolidate relative imports above absolute ones per PEP 8 standards in tests/test_capabilities.py, tests/test_providers.py, tests/test_ui.py and tests/test_web.py - Remove orphaned Mermaid diagram visualizations from docs/API.qmd documentation file to reduce unnecessary large assets - Add project-specific gitignore entries for hidden artifacts including thoughts directory, .omo/.opencode cache files, generic .* patterns and tmp folder Remove extra blank lines in code blocks
Added `crlf_to_lf.sh` to ensure commited files is with lf line-endings and automatic configuration of git. Changed folder-names on `workflows` to `change_2_local_workflow`to avoid accidentally triggering github workflows at right now.
…emand - Pin @vitejs/plugin-react to ^6.0.0 (peer vite: ^8.0.0). The previous 4.3.4 only supported Vite <=6, which caused ERESOLVE on a fresh `npm install`. - Remove the .npmrc legacy-peer-deps workaround now that deps are compatible. - Regenerate package-lock.json from a clean install (no overrides); dist/ and node_modules/ stay gitignored. - Add vite.config.js using @vitejs/plugin-react. - serve --web builds webapp/dist on demand when missing and degrades gracefully (the API still serves) when Node/npm is absent. - Add pytest coverage for the on-demand build control flow and the Node-missing fallback (npm subprocess mocked, so the suite needs no Node install).
Standardize module docstrings, remove redundant file header comments, clean up import ordering in source and test files, update dependency specifications in pyproject.toml, and regenerate documentation visualizations.
There was a problem hiding this comment.
Pull request overview
This PR substantially expands code_agent’s developer experience and public surface area by introducing a typed, env-driven settings model, an OAP-inspired capability/audit layer, and a local FastAPI + React web UI for listing/invoking capabilities. It also updates documentation and adds/refreshes tests to align with the new structure and workflows.
Changes:
- Add typed settings (
code_agent/settings.py) +.env.example-based configuration and update docs accordingly. - Introduce a capability registry with audit receipts and a FastAPI endpoint (plus Vite/React SPA) to discover/invoke capabilities over HTTP.
- Expand and reformat tests/examples/scripts to validate new web/capability behavior and improve local developer tooling.
Reviewed changes
Copilot reviewed 87 out of 151 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/test_web.py | New tests for FastAPI web UI + build-on-demand SPA behavior. |
| tests/test_scaffold.py | Formatting/assertion cleanup for scaffold tests. |
| tests/test_preview.py | Refocus tests on agent/LLM helpers; formatting cleanup. |
| tests/test_graph.py | Clean imports/types/docstrings; adjust fixtures and assertions. |
| tests/test_generate_test_tool.py | Update generated-test expectations; improve sample module docstring. |
| tests/test_file_generator.py | Consolidate file helper tests and improve coverage/messages. |
| tests/test_code_agent.py | Reformat tests and remove duplicated file-helper coverage. |
| tests/test_code_agent_core.py | Formatting tweaks; align tests with updated helper usage patterns. |
| scatter_demo.py | Add return type + return value for saved plot path. |
| README.md | Update links/diagrams section and improve navigation paths. |
| pydoctor.ini | Add pydoctor configuration for API docs generation. |
| project_management/structure_tools/generate_archive_candidates.ps1 | New script to compute archival candidates from cleanup report. |
| project_management/structure_tools/filter_cleanup_report.py | Formatting/refactor for filtered cleanup report generation. |
| project_management/structure_tools/cleanup_scan.py | Refactor/typing improvements for cleanup scanner and reporting. |
| project_management/structure_tools/archive_candidates.ps1 | New script to move archive candidates into timestamped archive folder. |
| project_management/run_vis.sh | New “graceful” visualization generation script (pyreverse/mermaid). |
| project_management/run_tests.sh | New “graceful” pytest runner wrapper. |
| project_management/run_formatters.sh | New “graceful” formatter/analyzer runner (uv/ruff/isort/etc.). |
| project_management/run_autofix.sh | New “graceful” autofix runner for formatting + install. |
| project_management/run_analyzers.sh | New “graceful” analyzer runner (pytest + type/lint/docs). |
| project_management/build_docs.sh | New script for Quarto doc/pdf/README generation. |
| pre-push | New local pre-push aggregator script for formatting + visualization. |
| pre-commit-quick | New local “quick” script for autofix + tests aggregation. |
| Notes.md | Present in PR payload (no diff shown). |
| examples/demo_verbose.py | Update demo; (currently contains a runtime-breaking type annotation). |
| examples/code_agent_usage.py | Reformat + typing/docstring improvements for usage examples. |
| docs/TOOLS.qmd | Minor doc change (currently includes a broken empty image tag). |
| docs/ROADMAP.qmd | Update config wizard reference from JSON to .env. |
| docs/README.qmd | Doc link/style tweaks and typography normalization. |
| docs/QUICKSTART.qmd | Switch configuration instructions to .env workflow. |
| docs/INSTALLATION.qmd | Switch configuration instructions to .env workflow. |
| docs/FAQ.qmd | Switch configuration guidance to .env workflow. |
| docs/CONFIGURATION.qmd | Rewrite configuration docs around typed Settings model. |
| docs/CODE_AGENT.qmd | Update wording and config reference to .env. |
| docs/API.qmd | Update API docs to reference Settings/.env as config source. |
| crlf_to_lf.sh | Add helper script to normalize line endings and enforce .gitattributes. |
| constraints.txt | Minor comment typography change. |
| code_agent/utils/utils.py | Docstring formatting cleanup. |
| code_agent/utils/diff_utils.py | Reformat + docstring normalization for diff helpers. |
| code_agent/utils/init.py | Normalize __all__ ordering. |
| code_agent/ui/webapp/vite.config.js | Add Vite build config for SPA output to dist/. |
| code_agent/ui/webapp/src/main.jsx | Add React entrypoint mounting <App />. |
| code_agent/ui/webapp/src/App.jsx | Add SPA UI for listing/invoking capabilities. |
| code_agent/ui/webapp/package.json | Add SPA package definition + deps/scripts. |
| code_agent/ui/webapp/index.html | Add SPA HTML shell. |
| code_agent/ui/web.py | Add FastAPI app serving capability catalog + invocations + SPA. |
| code_agent/ui/init.py | Export CLI UI public helpers. |
| code_agent/tools/read_file_tool.py | Tool doc/typing cleanup; still reads file contents. |
| code_agent/tools/r_tool.py | Tool refactor/formatting; safer temp file handling. |
| code_agent/tools/notebook_tool.py | Tool refactor/typing; notebook operations and artifacts. |
| code_agent/tools/nlp_tool.py | Logging cleanup + safer handling of LLM response content. |
| code_agent/tools/new_file_tool.py | Tool refactor/typing; backup + error handling improvements. |
| code_agent/tools/linker_tool.py | Tool refactor/typing/docstrings; file read tool returning artifact. |
| code_agent/tools/generate_test_tool.py | Tool refactor; generate smoke-test scaffold with clearer import. |
| code_agent/tools/general_chat_tool.py | Tool refactor/typing/docstrings; LLM passthrough behavior. |
| code_agent/tools/format_code_tool.py | Tool refactor; factor python/R formatting steps. |
| code_agent/tools/edit_file_tool.py | Tool refactor; switch FileObject to dataclass + logging improvements. |
| code_agent/tools/init.py | Add module docstring + normalize exports list. |
| code_agent/settings.py | Add typed Settings model loaded from .env/env (prefixed). |
| code_agent/scaffold.py | Formatting + typing/docstring improvements; allow `root: str |
| code_agent/run_agent.py | Improve scaffold wrapper typing/docstring. |
| code_agent/README.qmd | Update configuration instructions to .env. |
| code_agent/providers/openai.py | New OpenAI provider implementing provider contract. |
| code_agent/providers/ollama.py | New Ollama provider with config loading + legacy fallback. |
| code_agent/providers/factory.py | New provider factory selecting implementation by config. |
| code_agent/providers/base.py | New provider protocol/base classes. |
| code_agent/providers/init.py | Export provider contract symbols. |
| code_agent/graph.py | Docstring/typing cleanup; minor refactor for tool graph creation. |
| code_agent/exceptions.py | Minor docstring typography normalization. |
| code_agent/core.py | Public helper refactor/typing cleanup (incl. append_file param naming issue). |
| code_agent/config/settings.bash | Minor formatting tweak. |
| code_agent/config/llm_config.json | Removed legacy JSON config file. |
| code_agent/ci/run_agent.py | Refactor CI runner script; safer subprocess usage and typing. |
| code_agent/ci/check_output.py | Minor formatting/typing cleanup. |
| code_agent/ci/init.py | Add CI module docstring. |
| code_agent/capabilities/tool_adapter.py | New tool→capability adapter with heuristic risk classification. |
| code_agent/capabilities/registry.py | New registry for discovery/dispatch + receipt recording. |
| code_agent/capabilities/envelope.py | New invocation request/response envelope models. |
| code_agent/capabilities/base.py | New capability protocol/base + risk class definitions. |
| code_agent/capabilities/audit.py | New hash-chained audit receipt log. |
| code_agent/capabilities/init.py | Export capability contract symbols. |
| code_agent/agents/persistent_agent.py | Refactor persistent agent to use message-based invocation. |
| code_agent/agents/base_agent.py | Refactor agent construction + default tools wiring. |
| code_agent/agents/init.py | Docstring cleanup. |
| code_agent/.github/change_2_local_workflows/llm-review.yml | Add example local LLM review workflow. |
| code_agent/main.py | Fix malformed module docstring. |
| code_agent/init.py | Expand explicit public API exports (capabilities + providers). |
| .pre-commit-hooks.yaml | Replace legacy ruff-only hooks with broader pre-commit hook set + local scripts. |
| .pre-commit-config.yaml | Update hook repos/revs; add local script hooks. |
| .gitignore | Expand ignores (currently includes an overly broad .* rule). |
| .github/workflows/docs.yml | Remove legacy docs workflow. |
| .github/workflows/ci.yml | Remove legacy CI workflow. |
| .env.example | Add env template documenting CODE_AGENT_-prefixed keys. |
| _quarto.yml | Minor typography + include visualization SVGs as resources. |
Files not reviewed (1)
- code_agent/ui/webapp/package-lock.json: Generated file
Suppressed comments (4)
code_agent/ui/web.py:65
InvokeBodysubclasses PydanticBaseModel, but it is also decorated with@dataclass. Mixingdataclasses.dataclasswith Pydantic models can break FastAPI's request-body parsing/validation and also makes the dataclass import unnecessary.InvokeBodyshould be a plain Pydantic model.
docs/CONFIGURATION.qmd:52- These environment variable names also need the
CODE_AGENT_prefix to matchSettingsConfigDict(env_prefix="CODE_AGENT_"); otherwise they won't override.envvalues.
docs/CONFIGURATION.qmd:58 - This example should export the prefixed setting key so it is picked up by
Settings(CODE_AGENT_OLLAMA_MODEL), otherwise the override won't take effect.
examples/demo_verbose.py:9 - The return annotation
-> Rreferences an undefined name; without postponed evaluation it raisesNameErrorwhen defining the function. Use a real type (e.g.Any) or quote the annotation.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+27
to
+28
| from dataclasses import dataclass | ||
| from pathlib import Path |
Comment on lines
+32
to
+36
| from code_agent.capabilities.envelope import InvocationRequest | ||
| from code_agent.capabilities.registry import CapabilityRegistry | ||
| from fastapi import FastAPI, HTTPException | ||
| from fastapi.staticfiles import StaticFiles | ||
| from pydantic import BaseModel, Field |
Comment on lines
+97
to
+115
| @app.post("/invoke") | ||
| def invoke_capability(body: InvokeBody) -> dict[str, Any]: | ||
| """Dispatch an invocation and return the response plus audit receipt. | ||
|
|
||
| Args: | ||
| body: Parsed request body (capability_id and params). | ||
|
|
||
| :return: A JSON object with ``response`` (the :class:`InvocationResponse`) | ||
| and ``receipt`` (the audit :class:`Receipt`) fields. | ||
|
|
||
| :raises HTTPException: 400 when the capability is unknown, high-risk, or the | ||
| params fail validation. | ||
| """ | ||
| request = InvocationRequest( | ||
| request_id=uuid.uuid4().hex, | ||
| capability_id=body.capability_id, | ||
| params=body.params, | ||
| caller="web", | ||
| ) |
Comment on lines
+154
to
+166
| @staticmethod | ||
| def _to_dict(result: Any) -> dict[str, Any]: | ||
| """Normalize an invocation result to a JSON-serializable dict. | ||
|
|
||
| :param result: The capability's output, typically an ``output_model`` | ||
| instance. | ||
| :return: A dict representation of the result. | ||
| """ | ||
| if isinstance(result, BaseModel): | ||
| return result.model_dump() | ||
| if isinstance(result, dict): | ||
| return result | ||
| return {"value": result} |
Comment on lines
+28
to
+32
| OLLAMA_SCHEME=http | ||
| OLLAMA_HOST=localhost | ||
| OLLAMA_PORT=11434 | ||
| OLLAMA_MODEL=llama3 | ||
| TEMPERATURE=0.7 |
Comment on lines
+5
to
+9
| sourced, in increasing precedence, from: | ||
|
|
||
| 1. the process environment variables, and | ||
| 2. a ``.env`` file at the project root (``OLLAMA_PORT``, ``OPENAI_API_KEY`` ...). | ||
|
|
Comment on lines
+1
to
3
| from langchain.messages import HumanMessage | ||
|
|
||
| from code_agent.agents.persistent_agent import get_persistent_agent |
| - **Agent Usage**: | ||
| > **User**: "Create a new Python file named `utils.py` in the `src` directory with a function that adds two numbers." | ||
|
|
||
| ![] |
Comment on lines
+49
to
53
| def append_file(root_dir: Path, content: str) -> Path: | ||
| """Append *content* to the file at *root_dir*. | ||
|
|
||
| The function opens the file in append mode, writes the content and | ||
| returns the absolute file path. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces several significant improvements and refactorings to the codebase, with a focus on configuration, developer tooling, documentation, and public API structure. The most important changes are summarized below.
Configuration and Documentation Enhancements:
.env.exampletemplate to provide a clear reference for environment variable configuration, replacing the previous approach of editingllm_config.jsonand making setup easier for new users. [1] [2]README.mdand Quarto documentation to include new package and class diagrams, improved navigation links, and clarified instructions for configuration and usage. [1] [2] [3] [4]Developer Tooling and CI/CD:
ruffhooks to a more comprehensive set of pre-commit hooks, including checks for large files, merge conflicts, symlinks, and more.setup-cfg-fmtandpyupgrade. [1] [2] [3]ci.yml,docs.yml) and introduced a new example workflow for local LLM-based code review (.github/change_2_local_workflows/llm-review.yml). [1] [2] [3]Public API and Code Structure:
code_agent/__init__.pyto explicitly expose a more complete and organized public API, including new capability and provider abstractions, aligning with OAP-inspired patterns.__main__.pyand agent initialization modules. [1] [2]Thematic grouping of key changes:
Configuration & Documentation
.env.examplefor easier environment setup and updated documentation to reference it. [1] [2]Developer Tooling
API & Code Structure
__init__.pyto expose a richer, more organized public API.These changes collectively improve the developer experience, code quality, and maintainability of the project.