April 4, 2026 5 min read Python fork

effGen

Abstract

effGen: Enabling Small Language Models as Capable Autonomous Agents

The Problem

Small‑language‑model (SLM) agents lack a production‑ready runtime: they need consistent prompting, tool orchestration, memory handling, and a way to expose protocols without writing boilerplate. Teams building autonomous agents spend most of their effort on glue code rather than on the model logic itself.

What This Does

effGen supplies a full‑stack framework that turns an SLM into a multi‑tool agent. Core orchestration lives in effgen/core/agent.py, which builds system prompts, resolves guardrails and drives the model’s generate calls (effgen/models/*_adapter.py). Built‑in tools such as the Python REPL, calculator and web search are under effgen/tools/builtin/.

Configuration is declarative: configs/config.yaml, configs/models.yaml and configs/tools.yaml describe agents, model endpoints and tool bindings. The CLI (effgen/cli.py) parses these files, sets up logging (effgen/utils/logging.py), and launches either a local run (agent_main) or a protocol server (effgen/tools/protocols/acp/server.py, .../mcp/server.py).

The repository also ships example agents (examples/basic/, examples/advanced/) that demonstrate single‑agent, multi‑agent and streaming use‑cases, plus a Docker deployment (Dockerfile, examples/deployment/docker-compose.yml).

How It Is Wired

Execution starts at effgen/cli.py – the main function (line 1959) is the top‑level entry point used by the effgen console script. main:

Calls setup_logging → effgen/utils/logging.py.
Loads configuration via effgen/config/loader.py (27 functions, 3 classes, 41 callers).
Instantiates Agent (effgen/core/agent.py) – the hub module (43 inbound imports). Agent.__init__ builds a AgentConfig, registers tools (effgen/tools/base_tool.py), and creates a MessageBus.

From there run_all_tests (used by CI) and run_agent drive the core loop:

Agent._generate → model adapters (effgen/models/anthropic_adapter.py, .../openai_adapter.py, etc.) perform the outbound inference call (10 functions call a model).
Tool calls are dispatched via effgen/core/tool_calling.py, which looks up the tool class in the registry (effgen/tools/registry.py) and executes its run method (e.g., effgen/tools/builtin/calculator.py).

The most‑connected modules are:

Module	Ca (importers)	Ce (imports)	Instability
`effgen/__init__`	43	19	0.31 (in cycle)
`effgen/core/agent`	33	22	0.40 (in cycle)
`effgen/tools/builtin/__init__`	25	14	0.36 (in cycle)
`scripts/verify`	0	30	1.00

Circular imports involve effgen/__init__.py, effgen/core/agent.py and effgen/tools/builtin/__init__.py, raising the risk of import‑time side effects.

External effects are limited to:

File I/O (28 functions) – e.g., model checkpoint loading, logging, and scripts/verify.py.
Network calls (22 functions) – model APIs, protocol servers, and optional Grafana dashboards.
Database access (11 functions) – long‑term memory uses SQLite (effgen/memory/long_term.py).

The call graph shows print used in 82 places and Agent in 69, indicating heavy reliance on console output for debugging rather than structured logs.

How To Use It

# Clone and install
git clone https://github.com/moses-y/effGen
cd effGen
python -m pip install -e .   # installs from pyproject.toml

Configuration – edit configs/config.yaml (agent defaults), configs/models.yaml (API keys, model identifiers) and configs/tools.yaml (enable/disable built‑ins). Example keys are referenced in configs/api_keys.yaml (not committed).

Run a basic agent

python -m effgen.cli --config configs/config.yaml --agent basic_agent

Start the ACP protocol server

python -m effgen.tools.protocols.acp.server --host 0.0.0.0 --port 8000

Docker

docker build -t effgen:latest .
docker run --rm -p 8000:8000 effgen:latest

The repository’s examples/ directory contains ready‑to‑run scripts (basic_agent.py, advanced_multi_tool_agent.py) that can be invoked with the same CLI flags.

Real‑World Use

A SaaS platform that offers “AI‑assisted research” can embed effGen as a microservice. The platform supplies an OpenAI key in configs/api_keys.yaml, selects the research_agent preset, and runs the ACP server behind an API gateway. Incoming requests are forwarded to the server, which spawns an Agent instance, calls the model for reasoning, and uses the built‑in retrieval tool to fetch indexed documents from the vector store (effgen/memory/vector_store.py). The whole flow touches the model (network), the SQLite memory DB (disk), and logs to stdout via the structured logger.

Code Health & Issues

Measured findings (static analysis)

HIGH – Pin GitHub Actions to commit SHA (.github/workflows/*.yml).
HIGH – Add a lockfile beside pyproject.toml.
MEDIUM – Declare least‑privilege permissions for GITHUB_TOKEN (.github/workflows/ci.yml).
MEDIUM – Enable Dependabot or Renovate (.github/dependabot.yml).
MEDIUM – Pin Docker base image by digest (Dockerfile).
MEDIUM – Set persist-credentials: false on checkout steps (.github/workflows/ci.yml).
MEDIUM – Add a non‑root USER to the image (Dockerfile).
MEDIUM – Pin dependency resolution to avoid known CVEs (e.g., torch@2.0.0, transformers@4.35.0).
LOW – Add timeout-minutes to workflow jobs (.github/workflows/ci.yml).

Additional observations: no lockfile, circular imports, deep nesting (max indentation depth 9) and oversized modules (effgen/core/agent.py ≈ 1850 LOC) increase maintenance cost. Broad except Exception clauses appear in several core files, reducing error visibility.

The Bottom Line

effGen delivers a usable, Docker‑compatible stack for turning SLMs into autonomous agents, with a clear separation of configuration, model adapters, and built‑in tools. The codebase is functional but suffers from high cognitive load (large hub modules, import cycles) and lacks reproducible builds (no lockfile, unpinned dependencies). It is suitable for teams ready to invest in refactoring the core modules and tightening the CI/CD pipeline before production deployment.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

236 files

Python170
Markdown24
YAML19
JSON6
Shell4
TOML1

ReactDockerTransformers

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["effgen<br/>109 modules"] g1["tests<br/>32 modules"] g2["examples<br/>25 modules"] g2 -->|106| g0 g1 -->|52| g0

Module dependencies

The 10 most depended-upon modules of 168, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_effgen___init__["__init__"] n1_effgen_core_agent["agent"] n2_effgen_tools_base_tool["base_tool"] n3_ffgen_tools_builtin___init__["__init__"] n4_effgen_models_base["base"] n5_effgen_presets___init__["__init__"] n6_gen_tools_builtin_calculator["calculator"] n7_en_tools_builtin_python_repl["python_repl"] n8_fgen_tools_builtin_bash_tool["bash_tool"] n9_effgen_core_task["task"] n0_effgen___init__ --> n1_effgen_core_agent n0_effgen___init__ --> n9_effgen_core_task n0_effgen___init__ --> n5_effgen_presets___init__ n1_effgen_core_agent --> n4_effgen_models_base n1_effgen_core_agent --> n2_effgen_tools_base_tool n5_effgen_presets___init__ --> n0_effgen___init__ n3_ffgen_tools_builtin___init__ --> n7_en_tools_builtin_python_repl n3_ffgen_tools_builtin___init__ --> n6_gen_tools_builtin_calculator n3_ffgen_tools_builtin___init__ --> n8_fgen_tools_builtin_bash_tool n8_fgen_tools_builtin_bash_tool --> n2_effgen_tools_base_tool n6_gen_tools_builtin_calculator --> n2_effgen_tools_base_tool n7_en_tools_builtin_python_repl --> n2_effgen_tools_base_tool classDef cyc stroke:#ef4444,stroke-width:2px; class n0_effgen___init__,n1_effgen_core_agent,n3_ffgen_tools_builtin___init__,n5_effgen_presets___init__ cyc;

Dependencies

15 of 45 declared dependencies are a major version behind. Resolved 45 of 45 against the registry.

Package	Declared	Latest	Behind
`cryptography`	>=41.0.0	50.0.0	9 major
`protobuf`	>=3.20.0	7.35.1	4 major
`datasets`	>=2.16.0	5.0.1	3 major
`sentence-transformers`	>=2.2.0	5.7.0	3 major
`openai`	>=1.3.0	3.1.0	2 major
`rich`	>=13.7.0	15.0.0	2 major
`nvidia-ml-py`	>=11.495.46	13.610.43	2 major
`psutil`	>=5.9.0	7.2.2	2 major

Findings

LowDependencies declared without a lockfile - non-reproducible builds pyproject.toml

Open in Code Brain → See its neighbourhood →

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium6

low1

Pin third-party GitHub Actions to a commit SHAhigh

.github/workflows

nwtgck/actions-netlify@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Declare least-privilege permissions for GITHUB_TOKENmedium4 occurrences

.github/workflows/ci.yml

4 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

3 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

Dockerfile

python:3.11-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Pin the resolution so a vulnerable version cannot installmedium248 occurrences

no lockfile, and the declared ranges reach pydantic@2.0.0 CVE-2024-3772 (critical) +1 more; torch@2.0.0 CVE-2025-32434 (critical) +27 more; transformers@4.35.0 CVE-2023-6730 (critical) +47 more; and 9 more package(s)

The range includes versions with published advisories and nothing in the repository records which one was resolved, so two installs a month apart can differ in whether they are vulnerable and neither is reproducible from what is committed.

Fix: Commit the lockfile, which fixes the resolution and makes this answerable.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/ci.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.

View on GitHub All Projects