mikoko guardian

The Problem

Conservation teams need a quick, conversational source of mangrove‑specific knowledge—species traits, site data, carbon credit estimates, and restoration guidance—without building a custom knowledge base from scratch.

What This Does

The repository implements a single‑agent API that answers five domain‑focused queries:

identify_mangrove_species – returns detailed info for Kenyan mangrove species.
get_site_information – supplies data on coastal mangrove sites.
calculate_carbon_storage – estimates carbon stock and credit value.
plan_restoration – produces a basic restoration plan with resource and cost hints.
answer_general_question – forwards open‑ended queries to a Gemini‑2.0 Flash LLM.

All logic lives in mikoko_guardian/agent.py, which defines the five functions listed above. The package initializer mikoko_guardian/__init__.py is empty, serving only as a namespace marker.

How It Is Wired

Entry point → request handling The repo does not contain an explicit server script (e.g., main.py or app.py). FastAPI is detected, but no FastAPI FastAPI() instance or route declarations appear in the source. Consequently, the control‑flow graph consists solely of the five top‑level functions in agent.py; there are no import edges, and both modules have zero inbound (Ca) and outbound (Ce) connections, indicating no internal wiring beyond the functions themselves.

Function responsibilities

File	Function	Core work	External touch
`mikoko_guardian/agent.py`	`identify_mangrove_species`	Returns a static dictionary of species facts.	None (pure data).
`mikoko_guardian/agent.py`	`get_site_information`	Returns static site metadata.	None.
`mikoko_guardian/agent.py`	`calculate_carbon_storage`	Computes carbon storage from supplied area & maturity parameters using simple arithmetic.	None.
`mikoko_guardian/agent.py`	`plan_restoration`	Builds a static plan template with placeholders for resources and timelines.	None.
`mikoko_guardian/agent.py`	`answer_general_question`	Calls the Gemini 2.0 Flash model (presumed via an imported client that is not present in the repo) and returns the LLM response.	Network I/O to Google AI Platform (implicit).

Because no routing or server glue exists, the blast radius of any change is limited to the single file that houses all logic. However, the lack of a central FastAPI app means the agent cannot be invoked over HTTP without adding a wrapper; this is the primary wiring gap.

Measured complexity Static analysis flagged deep nesting (max indentation depth 6) in agent.py, making the control flow harder to follow. Refactoring into early‑return guard clauses or extracting helper functions would improve readability.

How To Use It

Clone the repository

   git clone https://github.com/moses-y/mikoko-guardian
   cd mikoko-guardian

Create a Python environment (the repo already ships a agent-venv folder, but it is a snapshot, not a reproducible environment). Recommended:

   python3 -m venv .venv
   source .venv/bin/activate

Install dependencies – the repo does not provide a requirements.txt or pyproject.toml. At minimum, install FastAPI and the Gemini client you intend to use:

   pip install fastapi "google-generativeai>=0.2"

(Adjust package names to match your LLM client.)

Provide configuration – the README references a .env file for API keys, but none exists. Create one in the repository root, e.g.:

   GEMINI_API_KEY=your-key-here

Add a FastAPI wrapper (required because no entry point is present). Example minimal app.py:

   from fastapi import FastAPI
   from mikoko_guardian.agent import (
       identify_mangrove_species,
       get_site_information,
       calculate_carbon_storage,
       plan_restoration,
       answer_general_question,
   )

   app = FastAPI()

   @app.get("/species")
   def species(name: str):
       return identify_mangrove_species(name)

   # Add similar routes for the other functions …

Run the service

   uvicorn app:app --reload

Without the wrapper, there is no runnable component.

Real‑World Use

A coastal NGO could deploy the FastAPI wrapper on a modest cloud VM, expose /species, /site, /carbon, and /plan endpoints, and let field staff query via a simple web UI or Slack bot. The LLM endpoint (answer_general_question) would require a valid Gemini API key in the .env file.

Code Health & Issues

Medium – Deep nesting – mikoko_guardian/agent.py and agent-venv/Include/site/python3.12/greenlet/greenlet.h have indentation depth 6, making logic harder to trace.
Medium – No tests – repository contains no tests/ directory or test files.
Medium – No CI/CD – no .github/ workflows, Dockerfile, or other automation scripts.
Medium – No LICENSE – usage and redistribution terms are undefined.

No secrets were detected in the commit history.

The Bottom Line

The repo supplies a concise, domain‑specific knowledge layer for mangrove conservation, but it stops short of delivering an executable service. Adding a FastAPI entry point, a dependency manifest, and basic test coverage are required before the code can be deployed reliably. Engineers comfortable extending lightweight Python modules will find the core logic easy to integrate; teams looking for a ready‑to‑run API will need to build the missing scaffolding.