npcpy Agent Framework

The README says Agent includes high-impact tools such as sh, python, edit_file, and web_search by default; CodingAgent automatically executes model-produced code, and team members automatically receive configured MCP tools. No least-privilege policy, per-action confirmation, sandbox, scoped authorization, or execution preview is shown, so least_privilege and user_confirmation score 0. The material identifies local and cloud providers, remote MCP, and HuggingFace interactions, but does not fully document what data is transmitted, retained, or exposed, so data-flow transparency is only partial. The release workflow passes the PyPI token through a GitHub secret and uses read-only contents permission, but user-facing credential handling, redaction, and privacy guidance are absent. A publishing action is commit-pinned and CI performs builds, yet most dependencies are unpinned, Ollama is installed through a curl-to-shell pipeline, and lint plus several test groups are non-blocking; dependency security therefore scores 1. Shell execution, file writes, network access, downloads, training, and publishing are visible, but systematic effect controls are not, and no rollback facility is documented. Repository, project, organizational copyright, documentation, and PyPI attribution are clear enough for 2; unknown publisher verification is not treated as suspicious or used to infer unrelated quality.

The README, test files, and CI broadly describe the same NPC, Agent, Team, tool, and multi-provider system. However, some tests are top-level calls that only print responses, while server, Windows, web, and integration checks frequently use continue-on-error or “|| true”; lint is also non-blocking. Self-consistency is therefore only 1. Python 3.10–3.12, local and cloud providers, a lite installation, and package build checks provide ordinary dependency availability, scoring 2, but many capabilities still depend on large downloads, external services, or credentials. Failure reporting is largely limited to pytest output and CI summary messages; no consistent user-facing error taxonomy, recovery guidance, or provider-failure behavior is evidenced, so it scores 1.

The sources cover research, coding, image generation, knowledge graphs, multi-agent work, serving, and structured output, with multiple configurable models and providers; audience/scenario coverage and environment fit each score 2. The advertised surface is extremely broad, while unsupported scenarios, safety boundaries, resource limits, and a complete support matrix are not defined, leaving capability boundaries at 1. Persona directives, tool descriptions, and jinx descriptions help routing, but default tools and natural-language orchestration lack precise authorization or triggering rules, so trigger precision is 1.

The README has substantial sections, collapsible examples, and a project tree, but the supplied material is truncated and does not establish complete navigation, API organization, or operational documentation, so information architecture scores 2. Installation guidance is mostly “pip install npcpy” plus CI commands; optional extras, system dependencies, credentials, and provider setup are not comprehensively explained, resulting in 1. NPC, Agent, ToolAgent, CodingAgent, Team, NPCArray, and jinx terminology is generally consistent, though import paths vary and the concept surface is large, so naming stability is 2. Examples are unusually numerous and concrete, earning 3. No explicit known-limitations section is supplied, scoring 0. The standalone MIT license and README badge agree, earning 3. PyPI/release automation is visible, but no changelog, compatibility policy, or migration notes are shown, so versioning/changelog scores 1. Organizational copyright and an automated release path exist, but named maintainers, support routes, and security ownership are absent, leaving maintenance responsibility at 1.

The framework demonstrates plain, streaming, JSON, Pydantic, multi-agent collection, and server outputs that are generally ready for downstream use, so output usability scores 2, although static output contracts and error forms are incomplete. Combining multi-provider calls, personas, tools, knowledge graphs, and team orchestration offers credible marginal value, scoring 2, but the supplied sources do not establish a thoroughly differentiated advantage over alternatives. Time, monetary, and hardware costs for cloud APIs, searches, large model downloads, image generation, 70B models, and 50-epoch training are barely addressed, so cost-benefit guidance scores 1.

Several capabilities map to concrete README examples, test names, and CI steps, giving partial traceability, but the strong claim that the data layer “ensures compliance through software” lacks an explained mechanism, policy model, or supporting test, so claim traceability is 1. README, tests, and workflows provide some cross-source corroboration for imports, documentation examples, serving, SQL, tools, and package builds, earning 2; many checks are non-blocking and none were executed for this review. Generated example answers and promotional capability claims are not consistently separated from verified facts or guarantees, and the displayed model answers lack validation, so fact/inference separation scores 1.