Clean initial commit for HuggingFace

.github/CONTRIBUTING.md

@@ -0,0 +1,103 @@
+# Contributing Guidelines
+
+Welcome to the project! 🎉  
+We move fast, but we keep code quality and stability in check.
+
+---
+
+## 🏗️ Branching Model
+
+- **main** → Always stable and demo-ready.  
+- **dev** → Integration branch.  
+- **feature/<name>** → Active development branches.
+
+**Flow:**
+1. Branch off `dev` for your work.
+2. Open a Pull Request (PR) into `dev`.
+3. Once `dev` is stable, it’s merged into `main` via a PR + review.
+
+Example:
+main ← dev ← feature/email-agent
+
+
+---
+
+## ✅ Pull Request Rules
+
+- All merges into `main` or `dev` **require at least one approving review**.
+- Keep PRs **small and focused** (<300 lines if possible).
+- Use **clear titles** and **short descriptions** (what + why).
+- You can **open draft PRs early** for feedback.
+- Squash merge when possible to keep history clean.
+
+**Naming Convention:**
+- `feat`: add Gmail OAuth flow
+- `fix`: handle missing image extraction
+- `docs`: update setup instructions
+
+
+---
+
+## ⚙️ Branch Protection
+
+**main**
+- Requires PR review before merging  
+- Requires status checks to pass (CI, tests, lint)  
+- Must be up-to-date with base before merging  
+- No direct commits or force pushes  
+
+**dev**
+- Requires PR review before merging  
+- Requires at least 1 approval  
+- Conversations must be resolved  
+- Status checks optional (for fast iteration)  
+- No direct commits or force pushes  
+- Squash or rebase merges only (no merge commits)
+
+---
+
+## 🚀 Quick Workflow
+
+1. `git checkout dev`
+2. `git pull`
+3. `git checkout -b feature/my-new-feature`
+4. Make your changes.
+5. Push & open a PR → base: `dev`
+6. Request a review.
+7. Merge when approved and tests pass.
+8. Once stable, open a PR from `dev → main`.
+
+---
+
+## 🧹 Hygiene
+
+- Delete merged branches.
+- Use Conventional Commits for clarity.
+- Keep `main` always deployable/demo-ready.
+- If you break something, fix it fast 😉
+
+---
+
+## 💬 Reviews
+
+- At least **one reviewer** per PR.  
+- Anyone can review — small teams move faster.  
+- **Pair reviews** encouraged for big changes.  
+- Minor changes (docs, comments) may be self-approved if trivial.
+
+---
+---
+
+## ⚙️ Branch Protection Setup (GitHub Rulesets)
+
+You can configure these under  
+➡️ **Settings → Code and automation → Rulesets**
+
+| Branch | Require PR | Required Approvals | Require Status Checks | Require Conversation Resolution | Allow Merge Commit | Force Push | Delete Branch |
+| :------ | :----------- | :----------------- | :-------------------- | :------------------------------ | :----------------- | :---------- | :------------- |
+| `main`  | ✅ | 1 | ✅ | ✅ | ❌ | ❌ | ❌ |
+| `dev`   | ✅ | 1 | optional | ✅ | ❌ | ❌ | ❌ |
+
+---
+
+Thanks for contributing — keep it fast, clean, and collaborative! 🚀

.gitignore

@@ -0,0 +1,70 @@
+
+# Ignore secret JSONs, not the folder
+secrets/**/credentials.json
+secrets/**/token.json
+
+secrets/**/calendar_credentials.json
+secrets/**/calendar_token.json
+
+# (Optional) ignore any backup or tmp credentials
+secrets/**/*_backup.json
+
+# any log files
+*.log
+
+__pycache__/
+*.pyc
+
+.env
+
+# pycahche files everywhere
+**/__pycache__/
+**/*.pyc
+**/.DS_Store
+
+
+# data
+src/database/cvs/uploads
+src/database/cvs/parsed
+src/database/voice_recordings
+
+
+
+# Local credentials / tokens
+.gcloud/
+.env
+.env.*
+**/credentials.json
+/results/
+
+# Terraform
+.terraform/
+*.tfstate
+*.tfstate.*
+crash.log
+terraform.tfvars
+*.auto.tfvars
+.override.tf
+override.tf
+
+
+# Ignore only .pdf and .txt files in uploads and parsed folders
+src/database/cvs/uploads/*.pdf
+src/database/cvs/uploads/*.txt
+src/database/cvs/parsed/*.pdf
+src/database/cvs/parsed/*.txt
+
+src/database/cvs/tests/*.pdf
+src/database/cvs/tests/*.txt
+
+# Keep these files
+!src/database/cvs/uploads/.gitkeep
+!src/database/cvs/parsed/.gitkeep
+!src/database/cvs/uploads/info.md
+!src/database/cvs/parsed/info.md
+
+# lamnggraph CLI cache
+.lgcache/
+.langgraph_api/
+
+.idea/

Dockerfile

@@ -0,0 +1,61 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# System dependencies
+RUN apt-get update && apt-get install -y gcc libpq-dev && rm -rf /var/lib/apt/lists/*
+
+# Copy requirement files
+COPY requirements/base.txt requirements/base.txt
+COPY requirements/db.txt requirements/db.txt
+COPY requirements/agent.txt requirements/agent.txt
+COPY requirements/supervisor.txt requirements/supervisor.txt
+COPY requirements/api.txt requirements/api.txt
+COPY requirements/cv_ui.txt requirements/cv_ui.txt
+COPY requirements/mcp_calendar.txt requirements/mcp_calendar.txt
+COPY requirements/mcp_gmail.txt requirements/mcp_gmail.txt
+COPY src/frontend/gradio/requirements.txt requirements/gradio.txt
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements/base.txt \
+    && pip install --no-cache-dir -r requirements/db.txt \
+    && pip install --no-cache-dir -r requirements/agent.txt \
+    && pip install --no-cache-dir -r requirements/supervisor.txt \
+    && pip install --no-cache-dir -r requirements/api.txt \
+    && pip install --no-cache-dir -r requirements/cv_ui.txt \
+    && pip install --no-cache-dir -r requirements/mcp_calendar.txt \
+    && pip install --no-cache-dir -r requirements/mcp_gmail.txt \
+    && pip install --no-cache-dir -r requirements/gradio.txt
+
+# Copy application code
+COPY src/ /app/src/
+COPY secrets/ /app/secrets/
+
+ENV PYTHONPATH=/app
+EXPOSE 7860
+
+# Create entry script inside the image (avoids missing file in build context)
+RUN printf '%s\n' \
+  '#!/usr/bin/env bash' \
+  'set -e' \
+  '' \
+  '# Hugging Face provides PORT; default to 7860 locally' \
+  'export PORT=\"${PORT:-7860}\"' \
+  '' \
+  '# Defaults for local in-container routing; can be overridden via env' \
+  'export SUPERVISOR_API_URL=\"${SUPERVISOR_API_URL:-http://127.0.0.1:8080/api/v1/supervisor}\"' \
+  'export DATABASE_API_URL=\"${DATABASE_API_URL:-http://127.0.0.1:8080/api/v1/db}\"' \
+  'export CV_UPLOAD_API_URL=\"${CV_UPLOAD_API_URL:-http://127.0.0.1:8080/api/v1/cv}\"' \
+  '' \
+  '# Start FastAPI backend' \
+  'uvicorn src.api.app:app --host 0.0.0.0 --port 8080 &' \
+  '' \
+  '# Give the API a moment to come up' \
+  'sleep 2' \
+  '' \
+  '# Run Gradio frontend' \
+  'python src/frontend/gradio/app.py' \
+  > /app/start.sh \
+  && chmod +x /app/start.sh
+
+CMD ["/app/start.sh"]

LICENSE

@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

README.md

@@ -0,0 +1,403 @@
+# ***`Recruitment Agent`***
+<p align="left">
+  <img src="https://img.shields.io/badge/MCP%20Hackathon-Track%202%20%E2%80%94%20Enterprise-blue" />
+  <img src="https://img.shields.io/badge/Model%20Context%20Protocol-Enabled-green" />
+  <img src="https://img.shields.io/badge/AI%20Agents-Recruitment-orange" />
+  <img src="https://img.shields.io/badge/Python-3.10%2B-blue" />
+  <img src="https://img.shields.io/badge/LangGraph-Agent%20Orchestration-purple" />
+  <img src="https://img.shields.io/badge/Gradio-UI%20Interface-yellow" />
+  <img src="https://img.shields.io/badge/HuggingFace-Platform%20%26%20Hackathon-black?logo=huggingface" />
+  <img src="https://img.shields.io/badge/OpenAI-LLM%20Powered-0A0A23?logo=openai" />
+  <img src="https://img.shields.io/badge/Google%20Cloud-APIs%20%26%20MCP%20Tools-blue?logo=googlecloud" />
+</p>
+
+
+
+
+
+
+> This project was developed as part of the **[MCP 1st Birthday Hackathon](https://huggingface.co/MCP-1st-Birthday)** — submitted under  
+> **Track 2: MCP in Action (Enterprise)**, showcasing a real-world multi-agent application built on top of the Model Context Protocol.
+
+
+<details>
+<summary><strong>📚 Table of Contents</strong> (click to expand)</summary>
+
+- [Problem Statement](#problem-statement)
+- [Ethical & Regulatory Considerations](#ethical--regulatory-considerations)
+- [Quick Start: Run Application](#quick-start-run-application)
+  - [Services & Ports](#services--ports)
+  - [Infrastructure & Secrets](#infrastructure--secrets)
+  - [Run Command](#run-command)
+  - [Resetting the Environment](#resetting-the-environment)
+- [Application Flow & Entry Points](#application-flow--entry-points)
+  - [The Recruitment Lifecycle](#1-the-recruitment-lifecycle)
+  - [User Entry Points](#2-user-entry-points)
+- [AI Engineering Principles](#ai-engineering-principles)
+  - [Prompt Engineering](#prompt-engineering)
+  - [Context Engineering](#context-engineering)
+- [Model & Agent Registry](#model--agent-registry)
+  - [Integrated MCP Servers](#integrated-mcp-servers)
+- [License & Acknowledgments](#license--acknowledgments)
+- [Team](#team)
+
+</details>
+
+
+
+
+## **Problem Statement**
+
+Modern recruitment processes remain **slow**, **resource-intensive**, and increasingly **unsustainable** for HR teams amid persistent talent shortages and evolving skill demands. Recent industry reports underscore structural bottlenecks that hinder efficient hiring.
+
+High **applicant volumes overwhelm recruiters**, with a *typical job posting attracting hundreds of applications*, many *unqualified*, leading to administrative burdens and rushed evaluations. This results in *only about **5%** of viewers completing applications*, while teams waste time sifting through low-quality submissions. [`1`]
+
+Screening and early-stage evaluation consume excessive recruiter time, with **35%** of their efforts dedicated to tasks like interview scheduling alone, exacerbating workload pressures. Talent acquisition leaders report unmanageable demands, with **27%** citing overload as a key issue, up from prior years. [`2`]
+
+**Hiring timelines average 44 days across industries**, driven by skills mismatches and manual processes that delay filling critical roles. Globally, **76%** of employers struggle to fill positions due to talent gaps, particularly in tech and healthcare sectors. [`1`, `3`]
+
+The financial toll is significant, with **average cost-per-hire reaching $4,700**, fueled by prolonged cycles, high turnover in recruitment teams (projected at **51%** as a top 2025 challenge), and inefficiencies in sourcing. [`1`, `2`]
+
+HR professionals **face rising burnout** from these pressures, compounded by competition for diverse talent and the **need for more touchpoints in hiring**, which **45%** of leaders say adds complexity. Skills shortages, cited by **63%** of employers as the primary barrier to growth, further strain teams. [`2`, `4`]
+
+These challenges reveal that **traditional manual recruitment fails to scale** in a competitive 2025 landscape. An AI-driven recruitment agent can alleviate bottlenecks by automating screening, accelerating timelines, enhancing consistency, and allowing HR to prioritize strategic decisions over repetitive tasks.
+
+
+
+### *`References`*
+
+1. [HR Cloud — 25 Recruitment Challenges & Solutions in 2025](https://www.hrcloud.com/blog/recruitment-challenges)
+
+2. [Select Software Reviews — 100+ Recruitment Statistics Every HR Should Know in 2025](https://www.selectsoftwarereviews.com/blog/recruiting-statistics)
+
+3. [Social Talent — The 2025 Hiring Reality Check](https://www.socialtalent.com/leadership/the-2025-hiring-reality-check-data-driven-answers-to-ta-leaders-top-questions)
+
+4. [World Economic Forum — The Future of Jobs Report 2025](https://www.weforum.org/publications/the-future-of-jobs-report-2025/digest/)
+
+## **Ethical & Regulatory Considerations**
+
+This project was developed as an **experimental prototype for a hackathon**, designed to showcase how language-model agents can automate structured workflows. It is **not intended for production deployment** as an autonomous hiring system. Because it touches on the automated assessment of humans, it must be approached with caution and interpreted within the correct ethical and regulatory context.
+
+The risks of algorithmic profiling have been widely documented, most notably during the **Cambridge Analytica scandal**, where data from millions of users was harvested and used for psychographic targeting without consent. This episode demonstrated how data-driven models can be leveraged to manipulate individuals when used irresponsibly, and it significantly shaped today’s regulatory landscape. [`5`]
+
+Given this history, any system that evaluates or ranks people—particularly in employment—must uphold **strict transparency, human oversight, and narrow scope**. In this prototype, all AI outputs are intended purely as **assistive signals**. The system must **never** be used to autonomously approve, reject, or shortlist candidates.
+
+The **EU AI Act** classifies AI systems used for recruitment, CV screening, candidate ranking, promotion decisions, or termination as **High-Risk AI Systems** (Annex III). Such systems are permitted in the EU but must meet stringent requirements, including:
+
+- **Human oversight** with the ability to override AI suggestions  
+- **Transparency** about the model’s role and limitations  
+- **Detailed logging and traceability** of system behavior  
+- **Bias monitoring and risk management**  
+- **High-quality and relevant training data**  
+- **Clear separation** between AI scoring and final human judgment
+
+The Act also **prohibits** certain practices in hiring, such as emotion recognition in workplace settings, biometric inference of personality traits, and social-scoring-style ranking systems. [`6`, `7`, `8`]
+
+This prototype **does not** conduct emotion recognition, sensitive-trait inference, biometric profiling, or psychographic prediction. It is a technical experiment focused on agent orchestration, workflow automation, and context management—not an end-to-end HR decision engine.
+
+### **Human-in-the-Loop by Design**
+To remain aligned with ethical expectations and regulatory requirements, this system must always operate with:
+
+- **Human-in-the-Loop (HITL):** Recruiters make all decisions.  
+- **Explainability:** Agents produce structured rationales, not black-box judgments.  
+- **Data minimization:** Only job-relevant information is processed.  
+- **No profiling of protected traits:** No biometric, psychographic, or emotional inference.
+
+### **Project Status**
+This project remains a **research and demonstration artifact**, created to explore the technical viability of LLM-powered coordination between agents. It highlights what is technologically possible, but is **not a deployable HR solution** under the EU AI Act. Any real-world implementation would require extensive risk assessment, compliance measures, and human oversight to avoid replicating the harms demonstrated in past profiling scandals.
+
+---
+
+### *`References`*
+
+5. [The Guardian — Cambridge Analytica: A Year On, Lesson in Institutional Failure](https://www.theguardian.com/uk-news/2019/mar/17/cambridge-analytica-year-on-lesson-in-institutional-failure-christopher-wylie)
+
+6. [High-level summary of the EU AI Act](https://artificialintelligenceact.eu/high-level-summary/)
+
+7. [EU Digital Strategy — Regulatory Framework for AI](https://digital-strategy.ec.europa.eu/en/policies/regulatory-framework-ai)
+
+8. [Clifford Chance — What Does the EU AI Act Mean for Employers?](https://www.cliffordchance.com/content/dam/cliffordchance/briefings/2024/08/what-does-the-eu-ai-act-mean-for-employers.pdf)
+
+
+
+## ***`Quick Start: Run Application`***
+To spin up the entire platform including the database, agents, and UI dashboards, we use **Docker Compose**.
+
+### ***Services & Ports***
+| Service | Description | Host Port | Container Port |
+|---------|-------------|-----------|----------------|
+| `db` | PostgreSQL 15 database with persistent storage | **5433** | 5432 |
+| `cv_upload_streamlit` | UI for uploading CVs | **8501** | 8501 |
+| `voice_screening_streamlit` | UI for voice screening candidates | **8502** | 8501 |
+| `supervisor_ui` | Main Chat UI for the Supervisor Agent | **8503** | 8501 |
+| `websocket_proxy` | Proxy for OpenAI Realtime API | **8000** | 8000 |
+
+### ***Infrastructure & Secrets***
+This project requires Google Cloud credentials for the Gmail and Calendar agents.
+
+- **Secrets:** Google tokens and credentials must be present in the `secrets/` directory.
+- **Infrastructure:** You can provision the necessary GCP infrastructure using the code in `terraform/` or the scripts in `scripts/infra/`.
+- **Documentation:** For detailed setup instructions, refer to the [MCP Docs](docs/mcp/).
+
+### ***Run Command***
+1. **Configure Environment:**
+   Copy the example environment file and fill in your API keys:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. **Start Services:**
+   ```bash
+   docker compose --env-file .env -f docker/docker-compose.yml up --build
+   ```
+
+### 🧹 Resetting the Environment
+If you need a clean slate (e.g., after modifying DB models):
+```bash
+# 1. Stop containers
+docker compose -f docker/docker-compose.yml down
+
+# 2. Remove persistent DB volume
+docker volume rm docker_postgres_data
+
+# 3. Rebuild & Start
+docker compose --env-file .env -f docker/docker-compose.yml up --build
+```
+
+---
+
+## ***`Application Flow & Entry Points`***
+
+The platform orchestrates a complete recruitment pipeline, interacting with both Candidates and the HR Supervisor.
+
+### 1. The Recruitment Lifecycle
+The system tracks candidates through a defined state machine (see `src/state/candidate.py` for the `CandidateStatus` enum).
+
+```mermaid
+graph TD
+    %% Actors
+    Candidate((Candidate))
+    HR((HR Supervisor))
+
+    %% System Components (Nodes)
+    CV_UI[CV Portal UI]
+    CV_Screen{CV Screening AI}
+    Voice_UI[Voice Portal UI]
+    Voice_Judge{Voice Judge AI}
+    Interview[Person-to-Person Interview]
+    Decision{Final Decision}
+
+    %% Flow & Actions (Edges)
+    Candidate -->|1. Uploads CV| CV_UI
+    CV_UI -->|2. Triggers Analysis| CV_Screen
+    
+    CV_Screen -->|Pass: Sends Invite| Voice_UI
+    CV_Screen -->|Fail: Notify| Rejected((Rejected))
+
+    Voice_UI -->|3. Conducts Interview| Candidate
+    Candidate -->|4. Completes Session| Voice_Judge
+    
+    Voice_Judge -->|Pass: Schedule| Interview
+    Voice_Judge -->|Fail: Notify| Rejected
+
+    Interview -->|5. Feedback| HR
+    HR -->|6. Updates Status| Decision
+    
+    Decision -->|Hire| Hired((Hired))
+    Decision -->|Reject| Rejected
+
+    %% Styling
+    style CV_UI fill:#e3f2fd,stroke:#1565c0
+    style Voice_UI fill:#e3f2fd,stroke:#1565c0
+    style CV_Screen fill:#fff3e0,stroke:#ef6c00
+    style Voice_Judge fill:#fff3e0,stroke:#ef6c00
+    style Interview fill:#e8f5e9,stroke:#2e7d32
+    style Decision fill:#f3e5f5,stroke:#7b1fa2
+```
+
+### 2. User Entry Points
+
+| User | Interface | Port | Description |
+| :--- | :--- | :--- | :--- |
+| **HR Manager** | **Supervisor UI** | `8503` | **The Command Center.** Chat with the Supervisor Agent to manage the pipeline, review candidates, query the DB, and schedule interviews. |
+| **Candidate** | **CV Portal** | `8501` | Public-facing portal for candidates to register and upload their resumes to the system. |
+| **Candidate** | **Voice Portal** | `8502` | AI-conducted voice interview interface. Candidates access this only after passing CV screening and receiving an invite. |
+
+---
+
+## ***`AI Engineering Principles`***
+
+### ***Prompt Engineering***
+
+To improve the reliability of complex evaluations (such as CV scoring and Voice Interview judging), we enforce **Chain-of-Thought (CoT)** reasoning within our structured outputs, inspired by [Wei et al. (2022)](https://arxiv.org/abs/2201.11903).
+
+By requiring the model to generate a textual explanation *before* assigning numerical scores, we ensure the model "thinks" through the evidence before committing to a decision. This is implemented directly in our Pydantic schemas (e.g., `src/agents/cv_screening/schemas/output_schema.py`), where field order matters:
+
+```mermaid
+flowchart LR
+    %% Nodes
+    Input[Input Data]
+    subgraph "Structured Output Schema"
+        Feedback["1. Generate Feedback (CoT)"]
+        Score["2. Assign Scores"]
+    end
+    Output[Overall Score]
+
+    %% Flow
+    Input --> Feedback
+    Feedback --> Score
+    Score --> Output
+
+    %% Styling
+    style Feedback fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
+    style Score fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
+```
+
+This simple structural constraint leads to significantly better calibration and reduced hallucination in scoring.
+
+### ***Context Engineering***
+
+To ensure long-running reliability and precision, this system employs a multi-layered approach to context management. This architecture prevents **"Context Rot"**—a phenomenon where LLM performance degrades as input length increases, as highlighted in [Chroma's research](https://research.trychroma.com/context-rot). By managing context effectively, we ensure agents remain focused and accurate over extended interactions.
+
+
+#### 1. Context Isolation via Delegation
+Instead of a single monolithic agent, tasks are delegated to **specialized sub-agents** (e.g., `cv_screener`, `voice_screener`).
+
+- **Delegate (Solid Arrow):** The Supervisor initiates a task, passing only the necessary context to a specific sub-agent.
+- **Report Back (Dotted Arrow):** Once the sub-agent completes its task, it returns a structured summary to the Supervisor, ensuring the main context remains clean.
+
+```mermaid
+graph TD
+    %% Legend (Top)
+    subgraph Legend [Legend]
+        direction LR
+        KeySup[Supervisor] -->|Delegation| KeyAgent[Sub-Agent]
+        KeyAgent -.->|Report Back| KeySup
+    end
+
+    %% Force Legend to be above Supervisor
+    Legend ~~~ Supervisor
+
+    Supervisor[🤖 Supervisor Agent]
+
+    %% Sub-Agents
+    Gmail[📧 Gmail Agent]
+    Cal[📅 GCalendar Agent]
+    DBExec[💾 DB Executor]
+    CV[📄 CV Screener]
+    Voice[🎤 Voice Screener]
+
+    %% Delegation (Outbound)
+    Supervisor --> Gmail
+    Supervisor --> Cal
+    Supervisor --> DBExec
+    Supervisor --> CV
+    Supervisor --> Voice
+
+    %% Feedback (Inbound)
+    Gmail -.-> Supervisor
+    Cal -.-> Supervisor
+    DBExec -.-> Supervisor
+    CV -.-> Supervisor
+    Voice -.-> Supervisor
+
+    %% Styling
+    style Supervisor fill:#e1bee7,stroke:#4a148c,stroke-width:2px
+    style Gmail fill:#fff3e0,stroke:#e65100
+    style Cal fill:#fff3e0,stroke:#e65100
+    style DBExec fill:#fff3e0,stroke:#e65100
+    style CV fill:#e3f2fd,stroke:#1565c0
+    style Voice fill:#e3f2fd,stroke:#1565c0
+    style Legend fill:#f5f5f5,stroke:#9e9e9e,stroke-dasharray: 5 5
+```
+
+- **How it works:** Each *sub-agent* operates in its *own isolated context/thread*.
+- **Benefit:** The main Supervisor is not polluted with low-level execution logs. Sub-agents are **stateless** from the Supervisor's perspective—each trigger starts a fresh thread, preventing error accumulation in the workers.
+
+
+#### 2. Context Offloading & Loading (RAG-lite)
+We treat the database not just as storage, but as **offloaded context**.
+- **Offloading:** Candidate data, screening results, and interview states are persisted immediately to a structured SQL/JSON database.
+- **Loading:** The Supervisor does not keep all candidate data in memory. Instead, it utilizes the `db_executor` agent to **retrieve (load)** only the specific data points needed for the current planning step.
+- **Benefit:** Keeps the active context window lean and focused on *reasoning* rather than *storage*.
+
+#### 3. Adaptive Context Compaction
+For the **stateful Supervisor** (which manages the long-running user conversation), we implement **Compactive Summarization**.
+- **Mechanism:** As the conversation history exceeds a token threshold, older interactions are summarized into a concise narrative while recent messages are kept verbatim.
+- **Result:** The agent retains "long-term memory" of the conversation arc without hitting context window limits, keeping the Supervisor "forever young."
+
+```mermaid
+graph TD
+    User[User / API] -->|Long-running Thread| Supervisor
+    
+    subgraph "Stateful & Compacted"
+    Supervisor[Supervisor Agent]
+    Memory[Context Compaction Module] -.->|Summarizes History| Supervisor
+    end
+
+    subgraph "Stateless & Isolated"
+    CV[CV Screener]
+    Voice[Voice Screener]
+    end
+
+    subgraph "Context Offloading"
+    DB[(Postgres DB)]
+    end
+
+    Supervisor -->|Delegates Task| CV
+    Supervisor -->|Delegates Task| Voice
+    Supervisor -->|Queries/Updates| DB
+    
+    CV -.->|1. New Thread| CV
+    Voice -.->|1. New Thread| Voice
+```
+
+## ***`Model & Agent Registry`***
+
+A breakdown of the various LLMs, Agents, and Workflows powering the system.
+
+- 🤖 **Agent:** Autonomous entity that can use tools, plan multiple steps, and maintain reasoning loops.
+- ⚙️ **Workflow:** Deterministic, fixed sequence of operations (Pipeline). It may use LLMs for specific steps but the flow is hardcoded.
+- 🧠 **Simple LLM:** A direct "one-shot" call to a Language Model for a specific transformation (e.g., summarization, extraction) without tools or loops.
+
+| Component | Type | Model | Description | Location |
+| :--- | :--- | :--- | :--- | :--- |
+| **Supervisor Agent** | 🤖 **Agent** | `gpt-4o` | Orchestrates delegation, planning, and context management. | `src/agents/supervisor/supervisor_v2.py` |
+| **Gmail Agent** | 🤖 **Agent** | `gpt-4o` | Autonomous email management via MCP (read/send/label). | `src/agents/gmail/gmail_agent.py` |
+| **GCalendar Agent** | 🤖 **Agent** | `gpt-4o` | Autonomous calendar scheduling via MCP. | `src/agents/gcalendar/gcalendar_agent.py` |
+| **DB Executor** | 🤖 **Agent** | `gpt-4o` | Writes SQL/Python to query the database (CodeAct). | `src/agents/db_executor/db_executor.py` |
+| **CV Screening** | ⚙️ **Workflow** | `gpt-4o` | Deterministic pipeline: Fetch → Read → Evaluate → Save. | `src/agents/cv_screening/cv_screening_workflow.py` |
+| **Voice Judge** | 🧠 **Simple LLM** | `gpt-4o-audio` | Evaluates audio/transcripts for sentiment & confidence. | `src/agents/voice_screening/judge.py` |
+| **Doc Parser** | 🧠 **Simple LLM** | `gpt-4o-mini` | Vision-based PDF-to-Markdown conversion. | `src/doc_parser/pdf_to_markdown.py` |
+| **History Manager** | 🧠 **Simple LLM** | `gpt-4o-mini` | Summarizes conversation history for context compaction. | `src/context_eng/history_manager.py` |
+
+### 🔌 ***`Integrated MCP Servers`***
+The system integrates **Model Context Protocol (MCP)** servers to securely and standardizedly connect agents to external tools.
+
+| MCP Server | Purpose | Used By |
+| :--- | :--- | :--- |
+| **Gmail MCP** | Provides tools to `list`, `read`, `send`, and `label` emails. | `Gmail Agent` |
+| **Google Calendar MCP** | Provides tools to `list_events`, `create_event`, and `update_event`. | `GCalendar Agent` |
+
+> **Note:** Each MCP server runs as a standalone process that exposes a standardized tool interface, which the respective agent consumes dynamically.
+
+---
+
+## ***`License & Acknowledgments`***
+This project utilizes code from:
+- [gmail-mcp](https://github.com/theposch/gmail-mcp) by **theposch** (GPLv3)  
+  *Integrated at:* `src/mcp_servers/gmail-mcp/`
+- [calendar-mcp](https://github.com/deciduus/calendar-mcp) by **deciduus** (AGPL-3.0)  
+  *Integrated at:* `src/mcp_servers/calendar-mcp/`
+
+We deeply acknowledge these original works and the great AI and Data Science community that makes such collaboration possible. We distribute our modifications under the compatible license terms.
+
+---
+
+## 👥 ***`Team`***
+| Member   |
+| -------- |
+| [Sebastian Wefers](https://github.com/Ocean-code-1995) |
+| [Dmitri Moscoglo](https://github.com/DimiM99) |
+| [Owen Kaplinsky](https://github.com/owenkaplinsky) |
+| [SrikarMK](https://github.com/Srikarmk) |

docker/Dockerfile.candidates_db_init

@@ -0,0 +1,22 @@
+# --- Dockerfile.candidates_db_init ---
+FROM python:3.12-slim
+
+# Set working directory inside container
+WORKDIR /app
+
+# Install system dependencies needed for psycopg2
+RUN apt-get update && apt-get install -y \
+    libpq-dev gcc && \
+    rm -rf /var/lib/apt/lists/*
+
+# Copy requirements file and install dependencies
+
+COPY ../requirements/base.txt ./requirements/base.txt
+COPY ../requirements/db.txt  ./requirements/db.txt
+RUN pip install --no-cache-dir -r requirements/db.txt
+
+# Copy *only* the candidate database module
+COPY src/database/candidates ./src/database/candidates
+
+# Default command - use dedicated init script to avoid circular import
+CMD ["python", "-m", "src.database.candidates.init_db"]

docker/Dockerfile.cv_upload

@@ -0,0 +1,29 @@
+# Use Python slim base
+FROM python:3.12-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    libpq-dev gcc && \
+    rm -rf /var/lib/apt/lists/*
+
+# Copy only requirements first (for build caching)
+COPY ../requirements/base.txt ./requirements/base.txt
+COPY ../requirements/db.txt ./requirements/db.txt
+COPY ../requirements/cv_ui.txt ./requirements/cv_ui.txt
+# Install Streamlit + base deps
+RUN pip install --no-cache-dir -r requirements/cv_ui.txt
+
+# Copy project source code
+COPY ../src ./src
+
+ENV PYTHONPATH=/app
+
+
+# Expose Streamlit port
+EXPOSE 8501
+
+# Default command to run Streamlit app
+CMD ["streamlit", "run", "src/frontend/streamlit/cv_ui/app.py", "--server.port=8501", "--server.address=0.0.0.0"]

docker/Dockerfile.supervisor

@@ -0,0 +1,36 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirement files
+COPY requirements/base.txt requirements/base.txt
+COPY requirements/db.txt requirements/db.txt
+COPY requirements/agent.txt requirements/agent.txt
+COPY requirements/supervisor.txt requirements/supervisor.txt
+COPY requirements/mcp_calendar.txt requirements/mcp_calendar.txt
+
+# Install dependencies directly (no venv needed in container)
+# **NOTE** uv isntallation is needed for the gmail mcp server to work.
+#          >>> it is installed in the base image /usr/local/bin/uv
+RUN pip install --no-cache-dir uv && \
+    pip install --no-cache-dir -r requirements/supervisor.txt && \
+    pip install --no-cache-dir -r requirements/db.txt && \
+    pip install --no-cache-dir -r requirements/agent.txt && \
+    pip install --no-cache-dir -r requirements/mcp_calendar.txt
+
+# Copy application code
+COPY src/ /app/src/
+COPY secrets/ /app/secrets/
+COPY .env /app/.env
+
+# Expose Streamlit port
+EXPOSE 8501
+
+# Run Streamlit
+CMD ["streamlit", "run", "src/frontend/streamlit/supervisor_ui/app.py", "--server.port=8501", "--server.address=0.0.0.0"]

docker/Dockerfile.supervisor_api

@@ -0,0 +1,43 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirement files
+COPY requirements/base.txt requirements/base.txt
+COPY requirements/db.txt requirements/db.txt
+COPY requirements/agent.txt requirements/agent.txt
+COPY requirements/supervisor.txt requirements/supervisor.txt
+COPY requirements/api.txt requirements/api.txt
+COPY requirements/cv_ui.txt requirements/cv_ui.txt
+COPY requirements/mcp_calendar.txt requirements/mcp_calendar.txt
+COPY requirements/mcp_gmail.txt requirements/mcp_gmail.txt
+
+# Install dependencies directly (no venv needed in container)
+# **NOTE** uv installation is needed for the gmail mcp server to work.
+#          >>> it is installed in the base image /usr/local/bin/uv
+RUN pip install --no-cache-dir uv && \
+    pip install --no-cache-dir -r requirements/supervisor.txt && \
+    pip install --no-cache-dir -r requirements/db.txt && \
+    pip install --no-cache-dir -r requirements/agent.txt && \
+    pip install --no-cache-dir -r requirements/api.txt && \
+    pip install --no-cache-dir -r requirements/cv_ui.txt && \
+    pip install --no-cache-dir -r requirements/mcp_calendar.txt && \
+    pip install --no-cache-dir -r requirements/mcp_gmail.txt
+
+# Copy application code
+COPY src/ /app/src/
+COPY secrets/ /app/secrets/
+COPY .env /app/.env
+
+# Expose API port
+EXPOSE 8080
+
+# Run FastAPI with uvicorn
+CMD ["uvicorn", "src.api.app:app", "--host", "0.0.0.0", "--port", "8080"]
+

docker/Dockerfile.voice_proxy

@@ -0,0 +1,29 @@
+# Use Python slim base
+FROM python:3.12-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    libpq-dev gcc && \
+    rm -rf /var/lib/apt/lists/*
+
+# Copy only requirements first (for build caching)
+COPY ../requirements/base.txt ./requirements/base.txt
+COPY ../requirements/db.txt ./requirements/db.txt
+COPY ../requirements/voice_proxy.txt ./requirements/voice_proxy.txt
+# Install Streamlit + base deps
+RUN pip install --no-cache-dir -r requirements/voice_proxy.txt
+
+# Copy project source code
+COPY ../src ./src
+
+ENV PYTHONPATH=/app
+
+
+# Expose FastAPI port
+EXPOSE 8000
+
+# Default command to run FastAPI proxy
+CMD ["python", "-m", "uvicorn", "src.frontend.streamlit.voice_screening_ui.proxy:app", "--host", "0.0.0.0", "--port", "8000"]

docker/Dockerfile.voice_screening

@@ -0,0 +1,28 @@
+# Use Python slim base
+FROM python:3.12-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    libpq-dev gcc && \
+    rm -rf /var/lib/apt/lists/*
+
+# Copy only requirements first (for build caching)
+COPY ../requirements/base.txt ./requirements/base.txt
+COPY ../requirements/voice_screening_ui.txt ./requirements/voice_screening_ui.txt
+# Install Streamlit + base deps
+RUN pip install --no-cache-dir -r requirements/voice_screening_ui.txt
+
+# Copy project source code
+COPY ../src ./src
+
+ENV PYTHONPATH=/app
+
+
+# Expose Streamlit port
+EXPOSE 8501
+
+# Default command to run Streamlit app
+CMD ["streamlit", "run", "src/frontend/streamlit/voice_screening_ui/app.py", "--server.port=8501", "--server.address=0.0.0.0"]

docker/docker-compose.yml

@@ -0,0 +1,236 @@
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~#
+# Run as follows from root:
+# >>> docker compose --env-file .env -f docker/docker-compose.yml up --build
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~#
+
+services:
+  # --- Database Service ---
+  # Runs a PostgreSQL 15 instance with persistent storage.
+  db:
+    image: postgres:15
+    container_name: agentic_hr_db
+    restart: always
+    ports:
+      - "5433:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U agentic_user -d agentic_hr"]
+      interval: 3s
+      timeout: 3s
+      retries: 5
+    environment:
+      POSTGRES_HOST: ${POSTGRES_HOST}
+      POSTGRES_PORT: ${POSTGRES_PORT}
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ${POSTGRES_DB}
+    networks:
+      - hrnet
+
+  candidates_db_init:
+    # --- Application Service ---
+    # Runs your Python backend inside Docker.
+    # Initializes the database or starts the API (depending on command).
+    container_name: candidates_db_init
+    build:
+      context: .. # build from the project root
+      dockerfile: docker/Dockerfile.candidates_db_init
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      POSTGRES_HOST: ${POSTGRES_HOST}
+      POSTGRES_PORT: ${POSTGRES_PORT}
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ${POSTGRES_DB}
+    # command: ["python", "-m", "src.database.candidates.init_db"]
+
+    volumes:
+      # --- Local code mount (for development only) ---
+      # Mounts your entire project source from the host (../)
+      # into the container at /app.
+      # ✅ Enables live code changes without rebuilding the image.
+      # ⚠️ Do NOT use in production – overrides the built image code.
+      - ../:/app # optional: live reload for local dev
+
+    networks:
+      - hrnet
+
+  # --- CV Upload ---
+  cv_upload_streamlit:
+    container_name: cv_upload_streamlit
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.cv_upload
+    ports:
+      - "8501:8501"
+    depends_on:
+      - db
+      - supervisor_api
+    environment:
+      # Database connection
+      POSTGRES_HOST: ${POSTGRES_HOST}
+      POSTGRES_PORT: ${POSTGRES_PORT}
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ${POSTGRES_DB}
+      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
+      CV_UPLOAD_PATH: /app/src/database/cvs/uploads
+      # App specific
+      CV_UPLOAD_API_URL: http://supervisor_api:8080/api/v1/cv
+      PYTHONPATH: /app
+    volumes:
+      # Mount local code for live updates
+      - ../:/app
+      # Shared volume for CV uploads (persistent)
+      - ../src/database/cvs:/app/src/database/cvs
+    command:
+      [
+        "streamlit",
+        "run",
+        "src/frontend/streamlit/cv_ui/app.py",
+        "--server.port=8501",
+        "--server.address=0.0.0.0",
+      ]
+    networks:
+      - hrnet
+
+  # --- WebSocket Proxy for OpenAI Realtime API ---
+  websocket_proxy:
+    container_name: websocket_proxy
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.voice_proxy
+    ports:
+      - "8000:8000"
+    depends_on:
+      - db
+      - candidates_db_init
+    environment:
+      PYTHONPATH: /app
+      OPENAI_API_KEY: ${OPENAI_API_KEY}
+      BACKEND_API_URL: http://supervisor_api:8080
+    volumes:
+      # Mount local code for live updates
+      - ../:/app
+    command:
+      [
+        "python",
+        "-m",
+        "uvicorn",
+        "src.frontend.streamlit.voice_screening_ui.proxy:app",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        "8000",
+      ]
+    networks:
+      - hrnet
+
+  # --- Voice Screening UI ---
+  voice_screening_ui:
+    container_name: voice_screening_ui
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.voice_screening
+    ports:
+      - "8502:8501" # Map host port 8502 to container port 8501
+    depends_on:
+      - db
+      - websocket_proxy
+    environment:
+      DATABASE_URL: postgresql://agentic_user:password123@db:5432/agentic_hr
+      PYTHONPATH: /app
+      WEBSOCKET_PROXY_URL: ws://websocket_proxy:8000/ws/realtime
+      BACKEND_API_URL: http://supervisor_api:8080
+    volumes:
+      # Mount local code for live updates
+      - ../:/app
+    command:
+      [
+        "streamlit",
+        "run",
+        "src/frontend/streamlit/voice_screening_ui/app.py",
+        "--server.port=8501",
+        "--server.address=0.0.0.0",
+      ]
+    networks:
+      - hrnet
+
+  # --- Supervisor Agent API ---
+  supervisor_api:
+    container_name: supervisor_api
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.supervisor_api
+    ports:
+      - "8080:8080" # Map host port 8080 to container port 8080
+    depends_on:
+      - db
+    environment:
+      # We set POSTGRES_HOST to 'db' so the agent connects to the container internal network
+      POSTGRES_HOST: ${POSTGRES_HOST}
+      POSTGRES_PORT: ${POSTGRES_PORT}
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ${POSTGRES_DB}
+      PYTHONPATH: /app
+      PROMPTLAYER_API_KEY: ${PROMPTLAYER_API_KEY}
+      OPENAI_API_KEY: ${OPENAI_API_KEY}
+      WEBSOCKET_PROXY_URL: ws://websocket_proxy:8000/ws/realtime
+    volumes:
+      # Mount local code for live updates
+      - ../:/app
+    command:
+      [
+        "uvicorn",
+        "src.api.app:app",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        "8080",
+        "--reload",
+      ]
+    networks:
+      - hrnet
+
+  # --- Supervisor Agent UI ---
+  supervisor_ui:
+    container_name: supervisor_ui
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.supervisor
+    ports:
+      - "8503:8501" # Map host port 8503 to container port 8501
+    depends_on:
+      - db
+      - supervisor_api
+    environment:
+      # We set POSTGRES_HOST to 'db' so the agent connects to the container internal network
+      PYTHONPATH: /app
+      # API URL for the Streamlit UI to connect to
+      SUPERVISOR_API_URL: http://supervisor_api:8080/api/v1/supervisor
+    volumes:
+      # Mount local code for live updates
+      - ../:/app
+    command:
+      [
+        "streamlit",
+        "run",
+        "src/frontend/streamlit/supervisor_ui/app.py",
+        "--server.port=8501",
+        "--server.address=0.0.0.0",
+      ]
+    networks:
+      - hrnet
+
+volumes:
+  postgres_data:
+  cvs_data:
+    driver: local
+
+networks:
+  hrnet:
+    driver: bridge

docker/info.md

@@ -0,0 +1,40 @@
+## 🐳 Docker Services
+
+### Services and Ports
+
+| Service | Description | Host Port | Container Port |
+|---------|-------------|-----------|----------------|
+| `db` | PostgreSQL 15 database with persistent storage | 5433 | 5432 |
+| `candidates_db_init` | Python backend container — initializes DB schema | N/A | N/A |
+| `cv_upload_streamlit` | Streamlit app for CV uploads | 8501 | 8501 |
+| `websocket_proxy` | WebSocket proxy for OpenAI Realtime API | 8000 | 8000 |
+| `voice_screening_ui` | Streamlit app for voice screening | 8502 | 8501 |
+| `supervisor_ui` | Streamlit app for Supervisor Agent | 8503 | 8501 |
+| `supervisor_api` | FastAPI backend for Supervisor Agent | 8080 | 8080 |
+
+---
+
+### Run Command
+
+```bash
+docker compose --env-file .env -f docker/docker-compose.yml up --build
+```
+
+---
+
+### Resetting the Environment
+
+When making structural changes to the database (e.g., modifying models, updating Enums) or when you simply want a clean slate for testing, the persistent Docker volumes may cause conflicts with new code.
+
+To completely reset the environment and database:
+
+```bash
+# 1. Stop running containers
+docker compose -f docker/docker-compose.yml down
+
+# 2. Remove the persistent database volume
+docker volume rm docker_postgres_data
+
+# 3. Rebuild and start fresh
+docker compose --env-file .env -f docker/docker-compose.yml up --build
+```

docs/agents/supervisor/mvps/mvp1/mvp_v1.md

@@ -0,0 +1 @@
+Owens

docs/agents/supervisor/mvps/mvp2/mvp_v2.md

@@ -0,0 +1,320 @@
+# ***MVP version #2***
+---
+
+
+## HR-Triggered Autonomous Workflow Concept
+
+The system is designed to operate **autonomously** while still allowing HR to initiate workflows and request status insights.  
+This ensures maximum automation without losing control or clarity in the process.
+
+---
+
+### **HR Interaction Trigger**
+
+When HR opens the UI, they can interact with the supervisor agent by asking questions such as:
+
+> **“Hey recruitment agent, what is the current status quo? Any new applicants? How many have passed CV screening?”**
+
+The supervisor agent then:
+
+1. Queries the database using predefined tools  
+2. Generates a clear, human-friendly status report  
+3. Waits for HR instructions on how to proceed  
+
+HR can then issue high-level commands like:
+
+- **“Process all new applicants.”**  
+- **“Do not process new applicants further — notify them instead.”**  
+- **“Continue processing only applicants who already passed screening.”**
+
+---
+
+### **Supervisor Executes Fully Autonomous Actions**
+
+Once HR gives the high-level command, the supervisor performs all actions autonomously:
+
+- **Process new applicants**  
+  - Parse CVs  
+  - Run CV screening  
+  - Update DB  
+  - Notify or proceed depending on results  
+
+- **Process screened applicants further**  
+  - Notify candidate  
+  - Request available time slots  
+  - Match HR availability  
+  - Schedule interview  
+  - Send confirmation emails  
+
+---
+
+### **Concurrency and Isolation**
+
+To avoid mixing contexts across candidates:
+
+- **Only one supervisor agent instance runs at a time**
+- Supervisor processes candidates **sequentially**
+- Each candidate is handled **individually and deterministically**
+
+This avoids:
+- Context bleed  
+- Duplicate actions  
+- Race conditions  
+- Mixed reasoning across candidates  
+
+---
+
+### **Per-Candidate Deterministic State Machine**
+
+Each candidate has a small state object:
+
+```json
+{
+  "candidate_id": 123,
+  "state": "cv_uploaded",
+  "checklist_path": "users/123/checklist.md"
+}
+```
+This keeps the workflow predictable, restartable, and isolated.
+
+---
+
+### ***Per-Candidate Checklist File***
+Each candidate has a personal Markdown checklist:
+```text
+# Candidate Checklist — ID 123
+
+- [x] CV uploaded
+- [x] CV parsed and stored
+- [x] CV screening started
+- [x] CV screening completed
+- [ ] Screening results notified to candidate
+- [ ] Asked candidate for available time slots
+- [ ] Received candidate availability
+- [ ] Checked HR availability
+- [ ] Scheduled interview
+- [ ] Final confirmation email sent
+```
+The supervisor uses this checklist to determine the next atomic action.
+It loads only this candidate’s context, performs exactly one update, writes back, and moves on.
+
+---
+## **Hybrid Progress Tracking — DB Status + Checklist**
+
+The HR agent maintains two synchronized layers of workflow state:
+
+- **Database `status` field:**  
+  Captures the **coarse-grained milestone** in the candidate’s lifecycle  
+  (e.g., `applied`, `cv_screened`, `interview_scheduled`, `decision_made`).  
+  → This is the **authoritative system state** used for HR dashboards, analytics, and reporting.
+
+- **Per-candidate Markdown checklist:**  
+  Tracks **fine-grained atomic actions** that occur within each milestone  
+  (e.g., CV parsed, CV screened, email sent, candidate replied).  
+  → This serves as the **agent’s operational log**, enabling deterministic reasoning, auditing, and safe restarts.
+
+---
+
+### **Checklist and Milestone Boundaries**
+
+The **checklist** is composed of multiple **substeps**, each representing one small, deterministic action.  
+When all substeps belonging to a stage are completed, the system reaches a **milestone boundary**.  
+That boundary marks a safe point to update the candidate’s `status` field in the database.
+
+| Milestone (`status` in DB) | Meaning | Checklist Substeps Leading to Boundary |
+|-----------------------------|----------|---------------------------------------|
+| `applied` | Candidate record created | `[x] CV uploaded`, `[x] CV parsed` |
+| `cv_screened` | Screening phase finished | `[x] Screening started`, `[x] Screening completed`, `[x] Result stored` |
+| `interview_scheduled` | Interview arranged | `[x] Candidate notified`, `[x] Availability received`, `[x] Interview scheduled` |
+| `decision_made` | Final decision delivered | `[x] Interview completed`, `[x] Decision logged`, `[x] Notification email sent` |
+
+---
+
+### **Sync Rule**
+
+1. After **each atomic substep**, the supervisor updates the checklist file.  
+2. When a **milestone boundary** is reached (all substeps for a phase checked off),  
+   the supervisor updates the corresponding `status` field in the database.  
+3. The checklist remains the **fine-grained operational truth**,  
+   while the database holds the **coarse-grained canonical truth**.
+
+---
+
+### **Summary**
+
+- **Checklist = micro-level progress tracker** (agent reasoning + recovery)  
+- **Milestone boundaries = transition triggers** (define when to sync with DB)  
+- **Database `status` = macro-level lifecycle state** (system-wide reference)
+
+This hybrid approach combines **LLM-friendly transparency** with **system-level consistency**, ensuring the agent can reason, recover, and scale safely.
+
+
+---
+
+### ***Result***
+This approach provides:
+- High autonomy
+- Strong safety boundaries
+- No context mixing
+- Clear state tracking
+- Reliable execution
+- HR keeps high-level control
+- LLM handles reasoning, routing, and next steps autonomously
+This structure is scalable, maintainable, and production-friendly while still pushing agent autonomy very far.
+
+
+## ⚡ ***Handling Everything Concurrently — The Async Supervisor Layer***
+---
+`The system must support concurrent processing of multiple candidate groups, each representing a different stage in the application pipeline (e.g., CV screening, voice screening, decision). Within each group, it should be able to process batches of candidates simultaneously while preserving per-candidate isolation and state consistency.`
+
+### **Thread-Based Per-Candidate Isolation For the Rescue**
+
+To ensure deterministic, fault-tolerant, and concurrent execution, the system leverages **LangGraph thread IDs** for per-candidate isolation:
+
+1. **Supervisor Delegation**  
+   The Supervisor Agent queries all candidates, groups them by their current `status` (e.g., CV screening, voice screening, decision), and passes the **list of candidate IDs** to the appropriate subagent tool.  
+   Each subagent handles its own data loading, ensuring the Supervisor remains lightweight and purely orchestration-focused.
+
+2. **Subagent Execution (Thread-per-Candidate)**  
+   Inside each subagent (e.g., `screen_cv`), the system iterates over all received candidate IDs.  
+   For each candidate:
+   - The **candidate ID serves as the `thread_id`**, providing a unique persistent context in LangGraph.  
+   - The subagent loads candidate data from the database (CV path, JD path, etc.).  
+   - The CV or voice screening logic runs **within that thread’s context**.  
+   - On completion, the results are written back to the database, and the per-candidate checklist and state are updated.
+
+3. **Parallel and Safe Processing**  
+   Subagents can process multiple candidates concurrently by spawning asynchronous executions per `thread_id`.  
+   Each candidate’s context remains isolated, preventing race conditions or context mixing.
+
+**Result:**  
+- Supervisor coordinates and dispatches candidate groups  
+- Subagents handle per-candidate logic using thread-based persistence  
+- Each candidate’s run is self-contained, recoverable, and writes its final results back to the database
+
+> **Note:**  
+> During a “Process All” operation, the Supervisor Agent executes **multiple reasoning loops**, invoking each subagent tool in sequence (e.g., `screen_cv`, `voice_screening`, `schedule_hr_interview`).  
+> After each tool call, it observes the result, reasons about the next step, and continues until all candidate groups are processed.
+
+
+
+Latest chat: https://chatgpt.com/share/6920d318-3f64-8012-8fca-b17316093131
+
+---
+
+> below mst be adapted based on section above:
+
+...
+```mermaid
+flowchart TD
+
+HR_UI[UI: HR opens dashboard<br/>and requests candidate status] 
+    --> REPORT[System returns report<br/>showing new and screened candidates]
+
+REPORT --> PARALLEL[Async Supervisor<br/>launches concurrent group tasks]
+
+%% --- New candidate path ---
+PARALLEL --> NEW_FLOW[Process new candidates<br/>CV screening pipeline]
+NEW_FLOW --> A[Delegate screening to subagent]
+A --> B[Subagent screens CV]
+B --> C[Write screening results to DB]
+C --> D[Supervisor receives results]
+D --> E{Did candidate pass screening?}
+E -- No --> REJECT[Notify candidate and HR<br/>application rejected]
+E -- Yes --> PASSED[Notify candidate and HR<br/>passed screening]
+
+%% --- Screened candidate path ---
+PARALLEL --> SCREENED_FLOW[Process screened candidates<br/>interview scheduling pipeline]
+SCREENED_FLOW --> I[Request candidate time slots]
+I --> J[Check HR calendar availability]
+J --> K[Schedule interview]
+K --> L[Notify HR and candidate<br/>interview confirmed]
+
+
+
+```
+
+To support concurrent processing across groups and candidates, the supervisor now operates as an asynchronous orchestrator.
+It remains a single agent context — responsible for reasoning, reporting, and orchestration — but leverages asyncio to execute multiple workflows concurrently.
+This allows the system to:
+- Process multiple groups (e.g., new vs. screened candidates) in parallel
+- Process multiple candidates per group concurrently
+- Maintain isolation and determinism per candidate through separate state/checklist files
+
+---
+
+Conceptual Overview
+1. HR issues a high-level command (e.g., “Process all candidates”).
+2. The supervisor queries the database and identifies candidate groups.
+3. It launches async tasks for each group simultaneously.
+4. Within each group, candidates are processed concurrently — each running the deterministic checklist logic described above.
+5. The supervisor awaits completion of all group tasks and reports progress and results.
+
+This preserves:
+- ✅ Single supervisor reasoning context
+- ✅ Concurrent group + per-candidate execution
+- ✅ Isolated per-candidate state and file I/O
+- ✅ High throughput without context bleed
+
+---
+
+***Conceptual Async Code Example***
+
+```python
+import asyncio
+from typing import List
+
+# --- Candidate-level deterministic flow ---
+async def process_candidate(candidate):
+    """Execute the per-candidate checklist and state transitions."""
+    state = await load_candidate_state(candidate.id)
+
+    if state == "cv_uploaded":
+        await parse_and_screen_cv(candidate)
+    elif state == "screened":
+        await schedule_interview(candidate)
+    # ... additional states here
+
+    await save_candidate_state(candidate.id, state)
+    print(f"✅ Candidate {candidate.id} processed ({state})")
+
+
+# --- Group-level concurrent handler ---
+async def process_group(candidates: List, group_name: str):
+    """Handle all candidates in one group concurrently."""
+    print(f"⚙️ Processing group: {group_name} ({len(candidates)} candidates)")
+    tasks = [process_candidate(c) for c in candidates]
+    await asyncio.gather(*tasks)
+    print(f"✅ Group {group_name} completed")
+
+
+# --- Main supervisor orchestration ---
+async def supervisor_run():
+    """Supervisor orchestrates all concurrent candidate workflows."""
+    print("🧠 Supervisor initialized")
+
+    # Query database and classify candidates
+    report = await get_candidate_report()
+    new_candidates = report["new"]
+    screened_candidates = report["screened"]
+
+    # Launch group workflows concurrently
+    await asyncio.gather(
+        process_group(new_candidates, "new_candidates"),
+        process_group(screened_candidates, "screened_candidates")
+    )
+
+    print("🎯 All candidate groups processed successfully")
+
+
+# --- Entry point ---
+if __name__ == "__main__":
+    asyncio.run(supervisor_run())
+```
+
+---
+***Key Properties***
+- **Async orchestration, single agent:** The supervisor coordinates all tasks without duplicating reasoning contexts.
+- **Per-candidate determinism:** Each checklist/state file is loaded, updated, and written atomically.
+- **Parallel group execution:** New and screened candidates can be processed simultaneously.
+- **Scalability path:** The same async structure can later integrate with LangGraph’s parallel nodes or distributed queues.

docs/agents/supervisor/mvps/mvp2/single_candidate_mvp.md

@@ -0,0 +1,257 @@
+
+# ***Single-Candidate MVP — Tick Box Milestones***
+---
+
+This V1 map outlines the simplest complete workflow for the HR agent system: HR enters the UI, receives a clear overview of all candidates and their screening status, and then chooses one of two actions—process new applicants or continue with those who are already screened. The supervisor then carries out the chosen workflow step-by-step, invoking the appropriate subagents (screening, Gmail, calendar) and updating each candidate’s state accordingly.
+
+
+## **V2 Workflow Diagram — HR → Supervisor → Actions**
+```mermaid
+flowchart TD
+
+    HR[HR opens UI] --> Q[Supervisor generates status report: applicants, screened, passed, failed]
+
+    Q --> HR_Decision{HR chooses action}
+
+    HR_Decision --> A[Option A: Process new applicant]
+    HR_Decision --> B[Option B: Process screened applicant]
+
+    %% Option A path
+    A --> A1[Supervisor triggers screening]
+    A1 --> A2[Subagent screens candidate]
+    A2 --> A3[Screening result stored in DB]
+    A3 --> A4[Candidate status updated]
+
+    %% Option B path
+    B --> B_DECISION{Candidate accepted or declined?}
+
+    B_DECISION --> B1A[If accepted: Gmail + Calendar workflow]
+    B_DECISION --> B1B[If declined: Gmail rejection email]
+
+    %% End nodes
+    A4 --> END((Done))
+    B1A --> END
+    B1B --> END
+
+```
+
+# Single-Candidate MVP — General Tick Box Milestones 
+
+## **1) CV Upload + Candidate Storage**
+- [ ] Candidate record created in DB (manual trigger OK)
+- [ ] CV file uploaded (manual OK for MVP)
+- [ ] CV parsed into structured format
+- [ ] Parsed CV stored in DB linked to candidate
+- [ ] Candidate status set to `uploaded`
+
+---
+
+## **2) Supervisor + Basic UI (Single Entry Point)**
+
+### **2.1 HR Status Query & Reporting**
+- [ ] Supervisor responds to: “What is the current status quo?”
+- [ ] Supervisor reports total number of applicants
+- [ ] Supervisor reports how many have been screened
+- [ ] Supervisor reports how many passed vs failed screening
+- [ ] Supervisor presents results as a clear HR-friendly summary report
+
+### **2.2 Supervisor Actions**
+- [ ] “Process new applicant” option available
+- [ ] “Process screened applicant” option available
+
+### **2.3 Action Logic**
+- [ ] Choosing “process new applicant” triggers initial screening workflow
+- [ ] Choosing “process screened applicant” triggers:
+  - [ ] Gmail + calendar workflow for accepted candidates
+  - [ ] Gmail rejection workflow for declined candidates
+
+### **2.4 State Updates**
+- [ ] Supervisor updates candidate status after each action
+- [ ] Supervisor logs each action outcome into DB
+
+---
+
+## **3) CV Screening Subagent**
+- [ ] Subagent loads candidate record
+- [ ] Subagent loads stored CV text
+- [ ] Subagent performs CV screening
+- [ ] Structured screening result saved to DB
+- [ ] Candidate status updated to `screened`
+- [ ] Supervisor UI reflects updated screening status
+
+---
+
+## **4) Per-Candidate Deterministic State Machine**
+- [ ] Each candidate has a dedicated state object (e.g., `state: "cv_uploaded"`)
+- [ ] State object persisted in DB or file
+- [ ] Supervisor reads this state before taking actions
+- [ ] Supervisor updates the state after actions
+- [ ] Workflow remains predictable and restartable per candidate
+- [ ] Each candidate’s context is isolated (no cross-candidate bleed)
+
+---
+
+## **5) Per-Candidate Checklist File**
+- [ ] A Markdown checklist file is created per candidate
+- [ ] Checklist is updated at each atomic step
+- [ ] Supervisor loads checklist to determine next required action
+- [ ] Checklist mirrors real workflow steps (upload → screening → notification → scheduling)
+- [ ] Checklist allows deterministic progress tracking
+- [ ] Checklist helps ensure one atomic action per supervisor step
+
+
+
+---
+
+
+# 🧭 Incremental Implementation Roadmap — From Skeleton to MVP
+
+This roadmap breaks the HR Agent MVP into incremental, testable phases.  
+Each phase builds on the previous one — keeping the system functional at every step while increasing autonomy, determinism, and traceability.
+
+A key invariant across all phases:
+> 🧩 **Each atomic action must update the per-candidate Markdown checklist**  
+> The checklist is the single source of truth for progress, state recovery, and auditability.
+
+***Checklist:***
+```text
+# Candidate Checklist — ID 123
+
+- [ ] CV uploaded, parsed and stored
+- [ ] CV screening (pass / fail)
+- [ ] Screening results notified to candidate & HR
+- [ ] Asked candidate for available time slots
+- [ ] Received candidate availability
+- [ ] Checked HR availability
+- [ ] Scheduled interview
+- [ ] Final confirmation email sent
+```
+---
+
+## **Phase 1 — Foundation Layer: Candidate I/O + Static State**
+
+Goal: Establish basic data persistence and candidate representation.  
+Outcome: You can manually create a candidate, attach a CV, and store structured data.
+
+- [ ] DB schema or JSON store for candidates  
+  - `candidate_id`, `name`, `cv_path`, `state`, `screening_result`
+- [ ] Manual script or simple UI form to create a candidate  
+- [ ] Upload CV file (manual or API endpoint)
+- [ ] Parse CV into structured format
+- [ ] Store parsed CV in DB
+- [ ] Candidate state set to `"cv_uploaded"`
+- [ ] ✅ **Checklist updated after each atomic step:**
+  - `[x] CV uploaded`
+  - `[x] CV parsed`
+  - `[x] Candidate stored`
+
+---
+
+## **Phase 2 — Supervisor Core Logic (CLI or Barebones UI)**
+
+Goal: Implement the supervisor agent’s reasoning + reporting loop for one candidate.  
+Outcome: HR can ask status questions and issue simple actions.
+
+- [ ] Simple command interface or Streamlit-like dashboard  
+- [ ] Supervisor responds to: “What’s the current status quo?”  
+- [ ] Supervisor reports:
+  - [ ] Total number of applicants  
+  - [ ] Number screened  
+  - [ ] Number passed vs failed  
+- [ ] HR can issue commands:
+  - [ ] `process_new_applicant`
+  - [ ] `process_screened_applicant`
+- [ ] Supervisor executes one step → updates candidate state  
+- [ ] State transitions logged  
+- [ ] ✅ **Checklist updated automatically after each supervisor action**
+
+---
+
+## **Phase 3 — Screening Subagent Integration**
+
+Goal: Automate CV evaluation and store results.  
+Outcome: Supervisor delegates screening to subagent and records outcome.
+
+- [ ] Subagent loads candidate record + parsed CV  
+- [ ] Runs screening model (mock or real)  
+- [ ] Produces structured result (e.g., `{passed: True, score: 85}`)  
+- [ ] Saves result in DB  
+- [ ] Candidate state transitions:
+  - `"cv_uploaded"` → `"screened_passed"` or `"screened_failed"`
+- [ ] Supervisor report reflects updated screening counts  
+- [ ] ✅ **Checklist updated:**
+  - `[x] Screening started`
+  - `[x] Screening completed`
+  - `[x] Result stored`
+
+---
+
+## **Phase 4 — Candidate Communication Layer (Gmail Integration)**
+
+Goal: Automate candidate notifications based on screening results.  
+Outcome: Supervisor triggers Gmail subagent to send emails.
+
+- [ ] Gmail subagent setup  
+- [ ] For `screened_failed`: send rejection email  
+- [ ] For `screened_passed`: send congratulations + request time slots  
+- [ ] Email status stored in DB  
+- [ ] Candidate state transitions:
+  - `"screened_failed"` → `"notified_rejection"`  
+  - `"screened_passed"` → `"awaiting_time_slots"`
+- [ ] ✅ **Checklist updated:**
+  - `[x] Candidate notified of result`
+  - `[x] Email status recorded`
+
+---
+
+## **Phase 5 — Interview Scheduling Layer (Calendar Integration)**
+
+Goal: Automate scheduling for passed candidates.  
+Outcome: Supervisor matches availability and books meetings.
+
+- [ ] Calendar subagent setup  
+- [ ] Candidate time slot parsing (from email reply or mock)  
+- [ ] Check HR calendar availability  
+- [ ] Schedule meeting and send confirmation email  
+- [ ] Candidate state transitions:
+  - `"awaiting_time_slots"` → `"interview_scheduled"`
+- [ ] ✅ **Checklist updated:**
+  - `[x] Candidate provided time slots`
+  - `[x] HR availability checked`
+  - `[x] Interview scheduled`
+  - `[x] Confirmation sent`
+
+---
+
+# Advanced System Features - Future Directions for Next MVP
+
+## **Phase 6 — Determinism + Persistence Layer**
+
+Goal: Make the system predictable, restartable, and auditable.  
+Outcome: Each candidate runs in isolation with explicit state and checklist.
+
+- [ ] Per-candidate state object stored in DB or JSON  
+- [ ] Per-candidate Markdown checklist file created:
+
+
+## **Phase 7 — Async Supervisor Orchestration (Scaling Up)**
+
+Goal: Extend single-candidate flow to multiple candidates concurrently.  
+Outcome: Async orchestration across candidate groups.
+
+- [ ] Async supervisor runs concurrently across groups:
+  - [ ] New candidates → screening path  
+  - [ ] Screened candidates → scheduling path  
+- [ ] Each candidate processed in an isolated coroutine  
+- [ ] Checklist + state ensure deterministic behavior per candidate  
+- [ ] Supervisor reports real-time progress  
+- [ ] Single reasoning context preserved  
+- [ ] ✅ **Each candidate’s checklist still governs progression, ensuring isolation and safe concurrency**
+- [ ] Supervisor awaits all async tasks and compiles final HR summary report  
+- [ ] System supports safe restarts (resume from last known checklist state)  
+- [ ] Scalable to LangGraph or distributed queue orchestration later on
+
+This roadmap breaks the HR Agent MVP into incremental, testable phases.
+Each phase builds logically on the previous one — so the system remains functional at every step while increasing in autonomy and complexity.
+
+---

docs/agents/supervisor/mvps/mvp2/tools_needed.md

@@ -0,0 +1,110 @@
+# ⚙️ Tools Required for MVP (Phases 1–5)
+
+The system consists of a **Supervisor Agent** (central orchestrator) and several **specialized subagents**.  
+Each tool corresponds to a specific capability needed for the single-candidate MVP flow — from CV upload to interview scheduling.
+
+---
+
+## 🧠 **Supervisor Agent (Core Orchestrator)**
+
+### **Role**
+Acts as the **central controller**:
+- Interfaces with HR (via UI or chat)
+- Handles reasoning, status reporting, and command interpretation
+- Orchestrates subagents (screening, Gmail, calendar)
+- Updates both the database and checklist after each atomic action
+
+### **Tools Required**
+
+| Tool | Purpose | Used in Phase |
+|------|----------|---------------|
+| 🗃️ **Database Tool / ORM Adapter** | Read, create, and update `Candidate` records (status, CV paths, results). | 1–5 |
+| 📄 **File I/O Tool** | Read/write per-candidate checklist and parsed CV files. | 1–5 |
+| 📊 **Reporting Helper / Aggregation Utility** | Query DB and summarize candidate counts (new, screened, passed, failed). | 2 |
+| 🧩 **Subagent Dispatch Interface** | Send structured tasks to subagents (screening, Gmail, calendar). | 3–5 |
+| 🧱 **State Manager** | Load and update candidate’s deterministic state object (`state`, `checklist`, `status`). | 4–5 |
+| 🕵️ **HR Command Parser / Intent Handler** | Interpret HR’s natural-language instructions (e.g., “process new applicants”). | 2 |
+
+---
+
+## 🤖 **Subagents & Their Tools**
+
+### **1. CV Screening Subagent**
+**Phase:** 3  
+**Purpose:** Automatically screen and score CVs.
+
+| Tool | Purpose |
+|------|----------|
+| 📄 **CV Parser** | Extract structured text from uploaded CV (PDF/DOCX). |
+| 🧮 **Screening Model / Classifier** | Evaluate parsed CV using rules or an ML/LLM-based model. |
+| 🗃️ **DB Access Tool** | Save screening results and update `Candidate.status = cv_screened`. |
+| 📄 **Checklist Writer** | Mark `[x] Screening started` and `[x] Screening completed` in the checklist. |
+
+---
+
+### **2. Gmail Subagent**
+**Phase:** 4  
+**Purpose:** Send automated emails to candidates based on screening results.
+
+| Tool | Purpose |
+|------|----------|
+| 📬 **Gmail API Wrapper** | Send templated emails (rejection or invitation). |
+| 🧠 **Template Manager** | Store and select appropriate email templates. |
+| 🗃️ **DB Access Tool** | Record email activity and update candidate state. |
+| 📄 **Checklist Writer** | Mark `[x] Candidate notified` and `[x] Email status recorded`. |
+
+---
+
+### **3. Calendar / Scheduling Subagent**
+**Phase:** 5  
+**Purpose:** Automate interview scheduling for passed candidates.
+
+| Tool | Purpose |
+|------|----------|
+| 🗓️ **Google Calendar API Wrapper** | Retrieve HR availability and create interview events. |
+| 📬 **Gmail API (reuse)** | Send scheduling confirmations and time slot requests. |
+| 🧠 **Availability Matcher** | Compare candidate-provided slots vs HR calendar availability. |
+| 🗃️ **DB Access Tool** | Update `Candidate.status = interview_scheduled`. |
+| 📄 **Checklist Writer** | Mark `[x] HR availability checked`, `[x] Interview scheduled`, `[x] Confirmation sent`. |
+
+---
+
+## 🧾 **Cross-Cutting Utilities (Shared by All Agents)**
+
+| Utility | Purpose | Used by |
+|----------|----------|----------|
+| 🧩 **Checklist Manager** | CRUD operations on per-candidate Markdown checklist files (load, mark, persist). | All |
+| 🧱 **State Sync Layer** | Sync checklist milestone boundaries with DB `status` updates. | Supervisor |
+| ⏱️ **Logging & Audit Utility** | Record all actions, errors, and state transitions. | All |
+| 🧮 **Config / Environment Loader** | Manage API keys, paths, and credentials for Gmail & Calendar. | All networked agents |
+
+---
+
+## 🧭 **Tool Overview by Phase**
+
+| Phase | Supervisor Tools | Subagents / Tools |
+|-------|-------------------|------------------|
+| **1 — Candidate I/O + Storage** | DB Adapter, File I/O, Checklist Manager | CV Parser (manual for MVP) |
+| **2 — Supervisor + UI** | HR Command Parser, DB Reporter, Checklist Manager | — |
+| **3 — CV Screening** | Subagent Dispatcher, Checklist Manager | CV Parser, Screening Model, DB Writer |
+| **4 — Candidate Communication** | Subagent Dispatcher, Checklist Manager | Gmail API, Template Manager |
+| **5 — Interview Scheduling** | Subagent Dispatcher, Checklist Manager | Calendar API, Availability Matcher, Gmail API |
+
+---
+
+## ✅ **Summary**
+
+- **Supervisor Agent Tools:**  
+  - DB Adapter  
+  - Checklist Manager  
+  - HR Interface (UI or CLI)  
+  - Subagent Dispatcher  
+  - State Sync Logic  
+
+- **Subagents:**  
+  - **Screening Subagent:** CV Parser + Screening Model  
+  - **Gmail Subagent:** Email Templating + Send API  
+  - **Calendar Subagent:** Scheduling + Availability Matching  
+
+Together, these tools form the complete single-candidate MVP pipeline —  
+from candidate intake → CV screening → communication → interview scheduling.

docs/agents/supervisor/mvps/overview.md

@@ -0,0 +1,64 @@
+# **Application Flow**
+
+## **MVP Version #2**
+
+
+```mermaid
+flowchart TD
+
+A[CV Upload] --> B[Store & Parse CV]
+
+B --> C[Trigger: CV Screening]
+
+C --> D[Supervisor Delegates<br/>Screening to Subagent]
+
+D --> E[Write Results to DB]
+
+E --> F[Supervisor Receives Screening Results]
+
+F --> G{Did Candidate Pass<br/>CV Screening?}
+
+G -- No --> H[Notify Candidate & HR:<br/>Application Rejected]
+
+G -- Yes --> I[Notify Candidate & HR:<br/>Passed Screening]
+
+I --> J[Request Candidate's<br/>Available Time Slots]
+
+J --> K[Check HR Calendar<br/>Availability]
+
+K --> L[Schedule Person-Person<br/>Interview]
+
+L --> M[Notify HR & Candidate<br/>Interview Confirmed]
+```
+
+The first goal is to ensure the application flows and works autonomously as follows:
+
+### **1) CV Submission**
+- Applicant submits CV  
+- CV is parsed and stored  
+
+### **2) CV Screening**
+- Supervisor agent becomes aware that a CV was uploaded  
+- A **“CV was uploaded” signal** triggers the supervisor to delegate **CV screening** to a sub-agent  
+- Results are written to the database & candidate status is updated  
+- A **“CV was screened” signal** notifies the supervisor that results are available and is able to read the results from db
+
+### **3) Success / Failure Notification**
+
+Based on CV screening results that the supervisor injected into its context, it decides:
+
+#### **a) Not Passed**
+- Trigger sub-agent to notify candidate *and* HR via email that the candidate did not meet requirements
+
+#### **b) Passed**
+- Trigger sub-agent to:
+  - Notify candidate and HR of the successful CV screening
+  - Ask candidate to provide several available time slots
+  - Check HR’s available time slots in their calendar
+  - Schedule a meeting based on overlapping availability  
+  - Notify HR that candidate X passed CV screening and that an interview was scheduled on **`dd-mm-yyyy`**
+
+
+
+## **Final**
+*(To be defined)*  

docs/agents/supervisor/supervisor_general.md

@@ -0,0 +1,120 @@
+# Supervisor Agent Overview
+This document explains the role, behavior, and context-engineering strategy of the Supervisor Agent used in the agentic HR recruitment system. It describes how the supervisor plans, coordinates, delegates, and adapts the multi-agent workflow, and how context is compressed, summarized, and managed to maintain robustness across long-running interactions.
+
+It also explains context-engineering strategies that are utilized in order to reduce token usage along with increasing reliability and task completion rate of the agents.
+
+---
+
+## 1. Purpose of the Supervisor Agent
+The Supervisor Agent serves as the centralized orchestrator responsible for maintaining global workflow control. Its role is to ensure that each subagent operates in the correct order, under the correct conditions, with the right context, and with full visibility into progress and failures.
+
+At a high level, the supervisor is responsible for:
+- Generating and maintaining the end-to-end hiring plan.
+- Determining which subagent should execute next.
+- Providing stateful context to each subagent.
+- Performing adaptive re-planning when outputs or conditions change.
+- Managing memory summaries and preventing context pollution.
+- Producing explainable logs and reasoning traces for the dashboard.
+
+This agent ensures that the entire HR pipeline behaves autonomously while remaining transparent, safe, and resilient.
+
+---
+
+## 2. High-Level Workflow
+The supervisor follows a structured, plan-driven execution model. The default plan is:
+
+1. CV Screening
+2. Voice Screening
+3. HR Interview Scheduling
+4. Final Decision Report
+
+However, execution is not strictly linear. The supervisor can skip, re-order, repeat, or halt steps based on subagent outputs.
+
+### Workflow Model
+1. **Initialize Plan**
+   - Build an initial sequence of workflow stages based on available candidate data.
+   - Load any relevant memory summaries or past runs from the database.
+
+2. **Select Next Stage**
+   - Evaluate current state.
+   - Choose the next subagent based on plan progress and real-time results.
+
+3. **Construct Subagent Context Package**
+   - Provide the subagent with the minimal context they need:
+     - Candidate details
+     - Results from prior stages
+     - Relevant memory summaries
+     - Tool call history (when helpful)
+     - Current workflow goal
+
+4. **Invoke the Subagent**
+   - The selected agent executes a task using LangGraph tool calls or MCP integrations.
+   - Outputs are validated and stored in state and database.
+
+5. **Reflect and Update Plan**
+   - The supervisor generates a lightweight reflection summary:
+     "What happened?", "Is the result valid?", "What is needed next?"
+   - If conditions changed, the supervisor updates the plan accordingly.
+     Examples:
+     - Skip voice screening if CV screening fails.
+     - Retry scheduling if the calendar shows no available slots.
+     - Pause and request HR confirmation when required.
+
+6. **Persist Memory**
+   - Summaries, transcripts, evaluations, and structured results are stored to prevent context bloating.
+   - Only relevant compact memory is injected back into future steps.
+
+7. **Repeat Until Complete**
+
+---
+
+## 3. Task Delegation Strategy
+The supervisor delegates tasks to subagents based on rule-based planning combined with lightweight LLM reasoning.
+
+### Delegation Logic
+- **CV Screening Agent** is invoked when a new applicant is added or a CV is updated.
+- **Voice Screening Agent** is invoked when the candidate passes CV screening and HR or the plan flags them as suitable for a phone screen.
+- **Scheduler Agent** is invoked once voice screening produces a valid transcript and evaluation.
+- **Decision Agent** is invoked after all stages complete, or when early rejection is clear.
+
+Each subagent returns structured outputs that the supervisor uses to drive the next step.
+
+---
+
+## 4. Adaptive Re-Planning
+One of the supervisor’s core responsibilities is to respond dynamically to real-world conditions.
+
+Examples of adaptive behaviors:
+
+- **Tool failure**: If Gmail or Calendar returns an MCP error, the supervisor retries, selects an alternative interaction path, or defers the step.
+- **Calendar constraints**: If no timeslots are available, the supervisor generates an alternate plan.
+- **Candidate status shifts**: If a candidate responds late or provides new documents, the supervisor reevaluates the plan.
+- **Voice call failure**: If the candidate does not pick up, the supervisor schedules a retry or sends an email follow-up.
+
+This makes the workflow robust, autonomous, and consistent with agentic paradigms.
+
+In unique situations, such as exceptional applicants, the agent can accellerate the timeline such as skipping stages. This is entirely discretionary and up to the agent's decision.
+
+---
+
+## 5. Context Engineering Strategy
+We utilize context engineering many times in the workflow. Each subagent instance is stateless, meaning that it doesn't retain any memory or context from previous turns. This allows for reduced token usage, since information from previous applicants is not relevant for new tasks. This state is reset every time it handles a unique task, but is retained until the supervisor determines the subagent has fully completed all necessary steps.
+
+Each time a subagent completes a task, the agent is given the full response. After the supervisor performs its next action, the subagent response is compacted into a high-level summary.
+
+The supervisor agent itself is also stateless in a sense: its context is applicant-dependant. Real-life timelines are messy, and multiple applicants will have steps overlap. Each time the supervisor agent needs to perform a new task, it loads the context from the user it is working on, and unloads it when it is done. This way, the supervisor is able to stay focused on a specific applicant and not get confused or distracted by managing multiple applicants at the same time. The state for this agent is saved in temporary files which are deleted once the applicant has a final decision made (hire or discard).
+
+---
+
+## 6. Explainability and Dashboard Integration
+The supervisor produces the trace outputs that power the Gradio dashboard.
+
+This includes:
+- Plan state (past, current, future)
+- Tool call logs
+- Reasoning and reflection summaries
+- Active memory excerpts
+- Subagent outputs
+- Error messages and fallback paths
+
+Because a single agent manages the plan, dashboard integration remains consistent and interpretable.

docs/agents/voice_screening.md

@@ -0,0 +1,336 @@
+# Voice Screening MVP
+
+## Overview
+
+The **Voice Screening MVP** provides a simple browser-based voice interview interface using Streamlit and OpenAI Realtime API. This is a simplified implementation that removes the complexity of LangGraph agents, Twilio telephony, and FastAPI servers.
+
+## Architecture
+
+**Simple MVP Architecture:**
+- **Streamlit UI**: Web interface with toggle recording button
+- **WebSocket Proxy**: FastAPI proxy for browser WebSocket authentication
+- **OpenAI Realtime API**: Real-time speech-to-speech via WebSocket
+- **Real-time transcription**: Live transcript display
+- **Real-time TTS**: Audio playback in browser with sequential queue
+- **Simple backend**: Post-session analysis and database storage
+
+## Components
+
+| Component | Purpose |
+|------------|----------|
+| **Streamlit UI** | Main interface with interview controls and transcript display |
+| **HTML/JavaScript Component** | WebSocket connection via proxy, audio recording/playback with queue |
+| **WebSocket Proxy** | FastAPI service to handle OpenAI authentication (browsers can't set custom headers) |
+| **OpenAI Realtime API** | Handles speech-to-text and text-to-speech in real-time (gpt-4o-mini-realtime-preview) |
+| **Analysis Function** | Simple GPT-4 analysis of transcript (no LangGraph) |
+| **Database Utilities** | Save results to database |
+
+## Flow
+
+```text
+User enters email and requests authentication code
+↓
+Proxy generates 6-digit code (MVP: displayed directly; production: sent via email/SMS)
+↓
+User enters email and code to verify
+↓
+Proxy validates code and returns session token
+↓
+User clicks "Start Interview"
+↓
+Browser opens WebSocket to WebSocket Proxy (with session token in query param)
+↓
+Proxy validates session token
+↓
+Proxy forwards connection to OpenAI Realtime API with API key authentication
+↓
+Proxy configures OpenAI session (modalities, instructions, voice, etc.)
+↓
+Proxy sends greeting request to OpenAI
+↓
+Agent greets candidate (first TTS response)
+↓
+User clicks mic button to start recording (toggle on)
+↓
+Browser streams audio chunks to OpenAI via proxy
+↓
+OpenAI returns transcriptions + TTS audio in real-time
+↓
+Audio chunks queued and played sequentially in browser
+↓
+Transcript shown live in Streamlit UI
+↓
+User clicks mic button again to stop and send (toggle off)
+↓
+Audio buffer committed to OpenAI
+↓
+User clicks "End Interview"
+↓
+Send transcript to backend for analysis
+↓
+GPT-4 analyzes transcript (sentiment, confidence, communication)
+↓
+Results saved to database
+```
+
+## Implementation Details
+
+### Streamlit UI (`src/voice_screening_ui/app.py`)
+
+**Features:**
+- **Authentication screen**: Email and code input fields
+- "Start Interview" button to initialize session
+- Toggle microphone button (click to start, click again to stop and send)
+- Live transcript display area
+- Session controls (end interview, logout)
+- Analysis and results display
+- Database integration
+- Debug panel for connection and audio troubleshooting
+
+**Session State:**
+- `session_token`: Authentication token from proxy
+- `user_email`: Authenticated user's email
+- `session_id`: Unique interview session identifier
+- `transcript`: List of transcript entries
+- `is_interview_active`: Boolean flag for active session
+- `candidate_id`: Candidate UUID
+
+### HTML/JavaScript Component (`src/voice_screening_ui/components/voice_interface.html`)
+
+**Features:**
+- WebSocket connection to WebSocket Proxy with session token authentication
+- Audio recording via browser ScriptProcessor API (PCM16)
+- Audio playback via Web Audio API with sequential queue
+- Real-time transcript updates
+- Toggle recording (click to start/stop)
+- Audio resampling from 24kHz to browser sample rate
+- Debug panel for troubleshooting
+
+**Key Functions:**
+- `connectWebSocket()`: Establishes connection to WebSocket Proxy (with session token)
+- `toggleRecording()`: Toggles recording state (start/stop)
+- `startRecording()`: Captures microphone audio and streams to API
+- `stopRecording()`: Stops recording and commits audio buffer
+- `handleRealtimeMessage()`: Processes responses from OpenAI
+- `queueAudioChunk()`: Queues audio chunks for sequential playback
+- `processAudioQueue()`: Plays audio chunks one at a time
+- `playAudioChunk()`: Decodes and plays individual TTS audio chunks
+
+**Note:** Session configuration and greeting are now handled by the proxy, not the client.
+
+### Analysis Function (`src/voice_screening_ui/analysis.py`)
+
+**Simple function** (no LangGraph):
+- Receives transcript text
+- Uses OpenAI GPT-4 with structured output
+- Returns `VoiceScreeningOutput` with scores and summary
+- No agent nodes or graph execution
+
+### Database Integration (`src/voice_screening_ui/utils/db.py`)
+
+**Function:**
+- `write_voice_results_to_db()`: Saves results to database
+- Updates candidate status to `voice_done`
+- Uses existing `VoiceScreeningResult` model
+
+### WebSocket Proxy (`src/voice_screening_ui/proxy.py`)
+
+**Features:**
+- **Authentication endpoints**: `/auth/login` and `/auth/verify`
+- **Session management**: In-memory token storage (MVP; use Redis/DB in production)
+- **WebSocket proxy**: `/ws/realtime` endpoint with session token validation
+- **Session configuration**: Handles OpenAI session setup server-side
+- **Greeting**: Automatically sends greeting after session configuration
+- **Health check**: `/health` endpoint for monitoring
+
+**Authentication Flow:**
+1. User requests code via `POST /auth/login` with email
+2. Proxy generates 6-digit code (MVP: returns directly; production: send via email/SMS)
+3. User verifies via `POST /auth/verify` with email and code
+4. Proxy validates and returns session token (valid for 1 hour)
+5. WebSocket connection requires `token` query parameter
+
+**Session Configuration:**
+- Moved from frontend to proxy for better security and control
+- Configured automatically when WebSocket connects
+- Includes modalities, instructions, voice, audio format, turn detection
+
+## Environment Variables
+
+```bash
+OPENAI_API_KEY=your_openai_api_key  # Required for Realtime API (stored in proxy only)
+```
+
+**Security:**
+- API key stored in proxy environment variables (never exposed to browser)
+- User authentication via email/code before WebSocket access
+- Session tokens expire after 1 hour
+- Auth codes expire after 10 minutes
+- Proxy handles all OpenAI authentication server-side
+
+## Usage
+
+### Running the Application
+
+```bash
+# Using Streamlit directly
+streamlit run src/voice_screening_ui/app.py
+
+# Or via Docker (Streamlit service)
+docker compose up voice_screening
+```
+
+#### troubleshootips tips
+
+- if you see a warning on env variable not being set, pass the .env manually and rebuild on down (subsequent build will be faste due to docker layer caching)
+``` bash
+cd docker
+docker-compose --env-file "../.env" up voice_screening -d --build
+```
+
+- run streamlit with python path set
+``` bash
+PYTHONPATH=. streamlit run src/voice_screening_ui/app.py
+```
+
+### User Flow
+
+1. Start WebSocket proxy: `docker compose up websocket_proxy` (or run `python src/voice_screening_ui/proxy.py`)
+2. Open Streamlit UI at `http://localhost:8502` (or configured port)
+3. **Authentication:**
+   - Enter your email address
+   - Click "Request Code" to get authentication code
+   - Enter the code and click "Verify & Login"
+4. Enter candidate email (optional for MVP)
+5. Click "Start Interview"
+6. Browser requests microphone permission
+7. WebSocket connects to proxy with session token (proxy connects to OpenAI Realtime API)
+8. Proxy configures session and sends greeting
+9. Agent greets candidate
+10. User clicks mic button to start recording
+11. User speaks, audio streams to OpenAI
+12. Transcript appears in real-time
+13. Agent responds with audio (played sequentially)
+14. User clicks mic button again to stop and send
+15. User clicks "End Interview"
+16. Click "Analyze Interview" to get results
+17. Optionally save results to database
+18. Click "Logout" to end session
+
+## Technical Details
+
+### OpenAI Realtime API
+
+**WebSocket Connection:**
+- Model: `gpt-realtime-mini`
+- URL: `wss://api.openai.com/v1/realtime?model=gpt-realtime-mini`
+- Headers: `Authorization: Bearer {API_KEY}`, `OpenAI-Beta: realtime=v1`
+- Format: PCM16 audio at 24kHz, JSON messages
+- Turn Detection: Server-side VAD with 10s silence duration (prevents auto-commit during recording)
+
+**Key Message Types:**
+- `session.update`: Configure session (modalities, voice, instructions)
+- `input_audio_buffer.append`: Send audio chunks
+- `input_audio_buffer.commit`: Commit audio for processing
+- `response.audio_transcript.done`: Receive transcriptions
+- `response.audio.delta`: Receive TTS audio chunks
+- `response.text.done`: Receive text responses
+
+### Audio Processing
+
+**Recording:**
+- Uses browser `ScriptProcessor` API (deprecated but functional)
+- Captures audio at browser sample rate (typically 44.1kHz or 48kHz)
+- Converts to PCM16 format
+- Encodes to base64 for WebSocket transmission
+- Streams chunks via `input_audio_buffer.append`
+- Commits buffer via `input_audio_buffer.commit` when recording stops
+
+**Playback:**
+- Receives base64 PCM16 audio at 24kHz
+- Decodes using `DataView` for proper byte order (little-endian)
+- Converts PCM16 to Float32Array
+- Resamples from 24kHz to browser sample rate using `OfflineAudioContext`
+- Queues chunks for sequential playback (prevents overlapping audio)
+- Plays through browser audio context
+
+## Simplifications from Original Design
+
+**Removed:**
+- LangGraph agent complexity
+- Twilio telephony integration
+- FastAPI server
+- Media Streams handling
+- Complex state management
+- Supervisor agent integration
+
+**Kept:**
+- Database models and utilities
+- Analysis logic (simplified)
+- Streamlit UI pattern
+- OpenAI Realtime API integration
+
+## File Structure
+
+```
+src/voice_screening_ui/
+├── app.py                    # Main Streamlit UI (with authentication screen)
+├── proxy.py                  # WebSocket proxy with auth endpoints and session management
+├── analysis.py               # Simple analysis function
+├── components/
+│   ├── voice_interface.html  # HTML/JS for WebSocket and audio (no API key handling)
+│   └── __init__.py
+└── utils/
+    ├── db.py                 # Database utilities
+    └── __init__.py
+```
+
+## Testing
+
+**Manual Testing:**
+1. Start Streamlit app (tested and works)
+2. Test WebSocket connection (tested and works)
+3. Test microphone access (tested and works)
+4. Test audio recording and playback (tested and works)
+5. Test transcript display (not tested)
+6. Test analysis function (doesn't work, need work, a lot of work)
+7. Test database saving (doesn't work, need work, a lot, a lot of work)
+
+### Verification Script
+To verify the integration of the voice screener with the candidate database and static questions, you can run the provided verification script.
+
+**Option 1: Run via Docker (Recommended)**
+This uses the containerized environment which already has all dependencies and network access to the database.
+```bash
+docker compose -f docker/docker-compose.yml run --rm -e POSTGRES_HOST=db websocket_proxy python tests/verify_voice_integration.py
+```
+
+**Option 2: Run Locally**
+If you prefer to run it locally, you need to install the database requirements first:
+```bash
+pip install -r requirements/db.txt
+python tests/verify_voice_integration.py
+```
+
+**Known Limitations:**
+- Uses deprecated `ScriptProcessor` API (should migrate to `AudioWorklet`)
+- Authentication codes displayed directly in MVP (should be sent via email/SMS in production)
+- Session tokens stored in-memory (should use Redis/database in production)
+- Simple error handling
+- Limited session management
+- Audio resampling may introduce slight latency
+
+## Future Enhancements
+
+- Migrate from `ScriptProcessor` to `AudioWorklet` API
+- Send authentication codes via email/SMS (instead of displaying directly)
+- Use Redis or database for session token storage (instead of in-memory)
+- Add session persistence across page refreshes
+- Improve error handling and reconnection logic
+- Add recording playback
+- Add interview question templates
+- Optimize audio resampling performance
+- Add audio level visualization
+- Add rate limiting for authentication endpoints
+- Add session refresh mechanism
+- Integrate with supervisor agent (if needed)

docs/context_engineering/ideas.md

@@ -0,0 +1,33 @@
+# ***Context Engineering***
+---
+
+This file serves as inspiration for context engneering techniques that are currently being used by experts in the industry.
+
+***Inpsired by:***
+- [Langchain](https://www.notion.so/Context-Engineering-for-Agents-2a1808527b17803ba221c2ced7eef508)
+- [Video](https://www.youtube.com/watch?v=XFCkrYHHfpQ&t=217s)
+
+
+## ***`What is context engineering?`***
+`The art and science to fill the context with just the right information for the next step.`
+
+[Chroma research](https://research.trychroma.com/context-rot) shows that increasing input tokens daramatically impacts llm performance.
+
+
+## Notes:
+
+### 1) Tool calls
+- tools calls bloat context as its added to messages list, with call itself + tool results
+- hence flush or summarise tools to reduce context length and keep context dense with just imoprtant info
+- furthermore tools are suually injected at sytem prompt level which bloats context as well and leads to confusion of wghich tool to use.
+
+
+### Context Offloading
+...
+
+
+### Context Compaction & Offloading
+
+
+
+

docs/entrypoint_patterns.md

@@ -0,0 +1,114 @@
+## 📄 How CV Parsing & LLM Evaluation Are Triggered — Summary
+
+Below is a clean overview of the three architectural patterns for triggering **CV parsing** and **LLM-based CV evaluation** inside an agentic HR pipeline.
+
+---
+
+## 🧩 End-to-End Flow
+1. Candidate uploads CV  
+2. System stores candidate entry in DB  
+3. CV parser runs automatically  
+4. Parsed CV JSON is stored in DB  
+5. Orchestrator detects that parsing is done  
+6. Orchestrator triggers the CV Screening Agent  
+7. LLM evaluates CV and stores results  
+8. Pipeline continues (voice → scheduling → final decision)
+
+---
+```sql
+[User (Streamlit UI)]
+   ↓
+   Upload CV + metadata (HTTP POST)
+   ↓
+[Orchestrator API]
+   ↓
+   Save CV file (local or cloud)
+   ↓
+   Write candidate entry to DB
+   ↓
+   Trigger parsing pipeline
+   ↓
+   Update parsed_cv_json + status='parsed'
+   ↓
+   Orchestrator runs CV Screening Agent
+   ↓
+   Write results to DB + status='cv_screened'
+   ↓
+[Streamlit polls /api/status/<candidate_id>]
+   ↓
+   Display updated status + scores
+```
+---
+
+## 🧠 Pattern A — Orchestrator-Driven State Machine (Recommended)
+
+The orchestrator continuously monitors the candidate’s status in the database and decides the next action based on that state.
+
+**Flow:**  
+- After parsing finishes, the system sets `status = "parsed"`  
+- The orchestrator checks the state and sees that the next step is CV screening  
+- It triggers the CV Screening Agent  
+- Once evaluation completes, the system updates status to `status = "cv_screened"`  
+- The orchestrator then moves to the next stage (voice screening, etc.)
+
+**Why this is the best choice:**  
+- Most “agentic” (planning + reasoning)  
+- Clean separation between deterministic parsing and cognitive reasoning  
+- Perfect fit for LangGraph orchestration  
+- Easy to visualize reasoning and workflow progress  
+- Ideal for hackathon judges (transparency + intentionality)
+
+---
+
+## 🧠 Pattern B — Event-Based Trigger (Webhook, Queue, Pub/Sub)
+
+The parsing component emits an event like “cv_parsed” when finished.  
+A listener or orchestrator receives that event and immediately triggers the CV Screening Agent.
+
+**Pros:**  
+- Scales well  
+- Good for microservice architectures  
+
+**Cons:**  
+- Less agentic  
+- Harder to show planning logic and state transitions  
+- More infrastructure complexity
+
+---
+
+## 🧠 Pattern C — Orchestrator Polling the Database
+
+A loop runs every few seconds, searching for candidates whose status is “parsed” and triggering CV evaluation when found.
+
+**Pros:**  
+- Very simple to implement  
+- Works well for demos and prototypes  
+
+**Cons:**  
+- Not reactive  
+- Less elegant  
+- Not as agentic or clean as Pattern A
+
+---
+
+## 🏆 Recommendation
+
+Use **Pattern A (Orchestrator-Driven State Machine)** for the hackathon submission.
+
+**Benefits:**  
+- Natural agentic behavior  
+- Works directly with LangGraph’s planning style  
+- Provides clear reasoning transparency  
+- Fits well with your multi-agent architecture  
+- Easy to show on the Gradio dashboard  
+- Minimal complexity while still highly principled
+
+---
+
+## 📝 TL;DR
+
+- CV parsing should run automatically after upload  
+- Parsed data should be saved to the DB  
+- **LLM CV evaluation should NOT be triggered by upload**  
+- Instead, the **orchestrator detects the new state and triggers evaluation**  
+- Pattern A (state machine) is the cleanest and most agentic solution

docs/how_langgraph_works.md

@@ -0,0 +1,262 @@
+# 🧭 LangGraph Overview: Message Flow, Tool Execution & GPT-OSS Integration
+LangGraph is a workflow engine for building agentic systems on top of LangChain.
+It models the reasoning–action loop between models and tools using a transparent graph of nodes.
+
+This document explains:
+1. How LangGraph message flow works
+2. How tools and tool calls are represented
+3. How your custom GPT-OSS (OpenRouter) wrapper integrates via bind_tools()
+
+---
+
+## ⚙️ Core Concept
+LangGraph passes a `state` object between nodes, usually defined like this:
+```python
+from typing import Annotated, List, TypedDict, Any
+from langgraph.graph.message import add_messages
+
+class State(TypedDict):
+    messages: Annotated[List[Any], add_messages]
+```
+
+The `messages` list holds the entire conversation: user inputs, model responses, and tool outputs.
+Each node reads this list, adds new messages, and returns an updated state.
+
+**LangGraph uses LangChain message objects:**
+- 🧑‍💼 HumanMessage — from the user
+- 🤖 AIMessage — from the model (may include tool_calls)
+- 🧰 ToolMessage — from a tool
+- ⚙️ SystemMessage — optional context
+
+## 🧩 The Typical Agent Flow
+```sql
+HumanMessage ─► LLMNode ─► ToolNode ─► LLMNode ─► Final Answer
+```
+
+### 1️⃣ Human input
+```python
+input_state = {
+    "messages": [
+        HumanMessage(
+            content="Compute 8 * 12 using calculator tool"
+        )
+    ]
+}
+```
+LangGraph starts from `START` and passes this to the first node (the model).
+
+### 2️⃣ Model response: tool call
+Your model (`ChatOpenRouter` running GPT-OSS) examines the conversation and returns an `AIMessage`:
+```json
+{
+  "content": "",
+  "tool_calls": [
+    {
+      "id": "call_1",
+      "function": {"name": "calculator", "arguments": "{\"a\":8,\"b\":12,\"op\":\"mul\"}"}
+    }
+  ],
+  "finish_reason": "tool_calls"
+}
+```
+✅ LangGraph detects `.tool_calls` and automatically routes the next step to the ToolNode.
+
+### 3️⃣ Tool execution
+The ***ToolNode*** executes the requested tool and adds a `ToolMessage` to the state:
+```python
+ToolMessage(
+    content='96.0',
+    name='calculator',
+    tool_call_id='call_1'
+)
+```
+
+### 4️⃣ LLM continuation
+The LLM now sees:
+```
+[
+  HumanMessage(...),
+  AIMessage(..., tool_calls=[...]),
+  ToolMessage(name="calculator", content="96.0")
+]
+```
+
+It generates a final summary message:
+```text
+"The result of 8 × 12 is **96**."
+```
+Since this new message has no further `tool_calls`, LangGraph ends the workflow.
+
+## 🧠 Internal Message Logic
+| Step | Message Type   | Produced By | Purpose             |
+| ---- | -------------- | ----------- | ------------------- |
+| 1    | `HumanMessage` | user        | Input               |
+| 2    | `AIMessage`    | model       | Requests tool       |
+| 3    | `ToolMessage`  | ToolNode    | Returns tool output |
+| 4    | `AIMessage`    | model       | Final answer        |
+
+
+LangGraph uses conditional edges to decide whether to continue looping:
+```python
+workflow.add_conditional_edges(
+    "agent",
+    lambda state: "tools" if state["messages"][-1].tool_calls else END
+)
+```
+This keeps running until no more tool calls are made.
+
+## ⚙️ Example Graph Definition
+```python
+from langgraph.graph import StateGraph, START, END
+from langgraph.prebuilt import ToolNode
+from langchain_core.messages import HumanMessage
+from langchain_core.tools import tool
+from src.core.llm_providers.openrouter_llm import ChatOpenRouter
+
+@tool
+def calculator(a: float, b: float, op: str) -> float:
+    """Perform a basic arithmetic operation."""
+    if op == "add": return a + b
+    if op == "sub": return a - b
+    if op == "mul": return a * b
+    if op == "div": return a / b
+
+tools = [calculator]
+
+# Initialize GPT-OSS LLM
+llm = ChatOpenRouter(model_name="openai/gpt-oss-120b", temperature=0.0)
+
+# ✅ Bind tools — this injects tool schemas into the model's context
+llm_with_tools = llm.bind_tools(tools)
+
+def call_model(state: State) -> State:
+    response = llm_with_tools.invoke(state["messages"])
+    return {"messages": [response]}
+
+workflow = StateGraph(State)
+workflow.add_node("agent", call_model)
+workflow.add_node("tools", ToolNode(tools))
+workflow.add_edge(START, "agent")
+workflow.add_conditional_edges(
+    "agent", lambda s: "tools" if s["messages"][-1].tool_calls else END
+)
+workflow.add_edge("tools", "agent")
+
+agent = workflow.compile()
+input_state = {"messages": [HumanMessage(content="Compute 8 * 12 using calculator tool")]}
+print(agent.invoke(input_state))
+```
+
+***>>> Check `notebooks/playground.ipynb` to see it in action!***
+
+```mermaid
+graph TD;
+  __start__(<p>__start__</p>)
+  agent(agent)
+  tools(tools)
+  __end__(<p>__end__</p>)
+  __start__ --> agent;
+  agent -->|tool_calls| tools;
+  tools --> agent;
+  agent -->|no tool_calls| __end__;
+  classDef default fill:#f2f0ff,line-height:1.2
+  classDef first fill-opacity:0
+  classDef last fill:#bfb6fc
+```
+
+## 🧩 How bind_tools() Works Internally
+`bind_tools()` is the bridge between LangGraph and your LLM.
+When you call:
+
+```python
+llm_with_tools = llm.bind_tools(tools)
+```
+
+LangChain:
+1. Extracts each tool's name, description, and argument schema.
+2. Converts them into an OpenAI function-calling schema JSON block (like `tools=[{"type":"function","function":{"name":...}}]`).
+3. Attaches that schema to the model's context before each inference call.
+So GPT-OSS sees an augmented prompt like this:
+> “You have access to the following tools:
+> calculator(a: float, b: float, op: str) — Perform a basic arithmetic operation.”
+
+
+During inference, the model can reason (internally) about which tool to call and output structured JSON like:
+```json
+{
+  "tool_calls": [{
+    "function": {
+      "name": "calculator",
+      "arguments": "{\"a\":8,\"b\":12,\"op\":\"mul\"}"
+    }
+  }]
+}
+```
+
+
+---
+
+## 🧱 GPT-OSS Integration via ChatOpenRouter
+To connect GPT-OSS via OpenRouter, use your wrapper:
+```python
+# src/core/llm_providers/openrouter_llm.py
+from langchain_openai import ChatOpenAI
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class OpenRouterSettings(BaseSettings):
+    OPENROUTER_API_KEY: str
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+class ChatOpenRouter(ChatOpenAI):
+    """OpenRouter wrapper for GPT-OSS and other open models."""
+
+    def __init__(
+        self,
+        model_name: str = "openai/gpt-oss-120b",
+        base_url: str = "https://openrouter.ai/api/v1",
+        temperature: float = 0.2,
+        **kwargs,
+    ):
+        settings = OpenRouterSettings()
+        super().__init__(
+            model_name=model_name,
+            openai_api_base=base_url,
+            openai_api_key=settings.OPENROUTER_API_KEY,
+            temperature=temperature,
+            **kwargs,
+        )
+```
+Then simply:
+```python
+llm = ChatOpenRouter()
+llm_with_tools = llm.bind_tools(tools)
+```
+✅ This passes your validated API key to the OpenRouter endpoint.
+
+✅ bind_tools() adds your tool schemas to the model input so GPT-OSS knows which functions exist.
+
+✅ LangGraph handles execution and looping automatically.
+
+
+---
+
+## 🔁 Full Flow Recap
+
+| Step | Component              | What Happens                                               |
+| ---- | ---------------------- | ---------------------------------------------------------- |
+| 1    | `ChatOpenRouter`       | Sends messages to GPT-OSS via OpenRouter API               |
+| 2    | `bind_tools()`         | Injects tool schema into model context                     |
+| 3    | `AIMessage.tool_calls` | Model outputs structured tool call                         |
+| 4    | `ToolNode`             | Executes the requested function                            |
+| 5    | `ToolMessage`          | Returns tool result to model                               |
+| 6    | `AIMessage`            | Model produces natural-language final answer               |
+| ✅    | LangGraph              | Orchestrates routing and maintains full conversation state |
+
+
+## ✅ TL;DR
+- LangGraph represents an agent loop as a message-passing graph.
+- Messages include `HumanMessage`, `AIMessage`, and `ToolMessage`.
+- `bind_tools()` injects your tool schemas into the LLM's context so it can call them.
+- The ToolNode executes the functions and feeds results back into the loop.
+- Your `ChatOpenRouter` wrapper lets GPT-OSS models participate in this system seamlessly.
+

docs/mcp/gmail_mcp_gcp_setup.md

@@ -0,0 +1,305 @@
+# ***`Gmail MCP – GCP Setup (Terraform + Bash)`***
+
+This folder provisions the minimum GCP infrastructure to run the [Gmail MCP server](https://github.com/theposch/gmail-mcp/tree/main) without requiring billing:
+- Creates (or adopts) a ***GCP project***
+- Enables ***gmail.googleapis.com***
+- Grants your user:
+- `roles/editor`
+- `roles/serviceusage.serviceUsageAdmin`
+Prints console links to finish OAuth (consent screen + Desktop client)
+> Billing is **not required** for Gmail API or OAuth Desktop client.
+
+## ***Prerequisites***
+- **Terraform** ≥ 1.6
+- **gcloud** (optional but useful for verifying/importing projects)
+- A Google account (you'll also add it as a **Test user** on the OAuth consent screen)
+
+## Files
+- `versions.tf` – provider & Terraform version pins
+- `providers.tf` – Google provider config (uses project_id and region)
+- `variables.tf` – input variables
+- `main.tf` – project, Gmail API enablement, IAM bindings
+- `outputs.tf` – project IDs and console URLs
+- `terraform.tfvars` – team defaults (simple `key = "value"` pairs)
+
+Example `terraform.tfvars`:
+```python
+project_id   = "gradio-hackathon-25"
+project_name = "Gradio Agent MCP Hackathon 25"
+user_email   = "hr.cjordan.agent.hack.winter25@gmail.com"
+# region    = "europe-west3" # optional
+```
+
+## ***Quick Start (recommended: use the scripts)**
+From the ***repo root***:
+1. **Authenticate gcloud + ADC**
+```bash
+chmod +x scripts/gcp_setup.sh
+./scripts/gcp_setup.sh
+```
+
+2. **Apply Terraform with smart defaults + auto-import**
+```bash
+chmod +x scripts/terraform_apply.sh
+./scripts/terraform_apply.sh
+```
+
+- The script **prompts** for `project_id`, `project_name`, `user_email`.
+- Press ***Enter*** to use defaults from `terraform/terraform.tfvars`.
+- If the project already exists, it is **auto-imported** to avoid `409 alreadyExists`.
+
+---
+
+## ***Manual Usage (alternative)***
+Run these from this `terraform/` directory:
+```bash
+terraform init
+
+# If the project already exists, import it so Terraform manages it:
+# terraform import google_project.project <your-project-id>
+
+terraform apply
+```
+
+Override values:
+
+```bash
+terraform apply \
+  -var="project_id=my-mcp-project" \
+  -var="project_name=My MCP Project" \
+  -var="user_email=you@example.com"
+```
+
+Or via env vars:
+```bash
+export TF_VAR_project_id="my-mcp-project"
+export TF_VAR_project_name="My MCP Project"
+export TF_VAR_user_email="you@example.com"
+terraform apply
+```
+
+## **Outputs**
+- `project_id` / `project_number`
+- `gmail_api_service` — `"gmail.googleapis.com"` (resource present ⇒ enabled)
+- `console_oauth_consent_screen_url` — configure consent (External, Test user, add scope)
+- `console_oauth_credentials_url` — create ***OAuth 2.0 Client ID*** (Desktop app)
+
+## **Final OAuth Setup (one-time, in Console)**
+
+Terraform cannot create the **OAuth consent screen** or **Desktop OAuth client**, so you'll do these two steps once in the Google Cloud Console.  
+This setup allows your **local Gmail MCP server** to access Gmail via OAuth securely.
+
+> 💡 **Tip:** In the new Google Cloud UI, the old “Scopes” and “Test users” tabs are now under **Data access** and **Audience** in the left sidebar.
+
+---
+
+### 1️⃣ **Configure the OAuth Consent Screen**
+
+**Purpose:** Identify your app to Google and specify who can use it during testing.
+
+1. Open the link printed in Terraform outputs:  
+   → `console_oauth_consent_screen_url`
+
+2. If prompted, choose **User type: External**, then click **Create**.
+
+3. Fill out **App info**:
+   - **App name:** `Gmail MCP Local`
+   - **User support email:** your Gmail address  
+   - **Developer contact email:** your Gmail address  
+   - Click **Save and Continue**
+
+4. In the left sidebar, go to **Data access**
+   - Click **Add or remove scopes**
+   - Add the following scopes:
+     ```text
+     https://www.googleapis.com/auth/gmail.modify
+     openid
+     https://www.googleapis.com/auth/userinfo.email
+     ```
+     ✅ *These provide read, send, and modify access — no extra Gmail scopes required.*
+
+5. Go to **Audience** (left sidebar)
+   - Under **Test users**, click **Add users**
+   - Add your Gmail account address  
+   - Click **Save**
+
+6. Go to **Summary** and confirm:
+   - User type → **External**
+   - Publishing status → **Testing**
+   - Test users → your Gmail account
+   - Scopes → shows Gmail modify, openid, userinfo.email
+
+---
+
+### 2️⃣ **Create a Desktop OAuth Client**
+
+**Purpose:** This provides the credentials your **local MCP server** uses to initiate the OAuth flow.
+
+1. Open the second Terraform output link:  
+   → `console_oauth_credentials_url`
+
+2. Click **Create credentials → OAuth client ID**
+
+3. Choose:
+   - **Application type:** `Desktop app`
+   - **Name:** `gmail-mcp-desktop`
+
+4. Click **Create**, then **Download JSON**, and move it into the expected directory:
+```bash
+mkdir -p ~/.gmail-mcp
+mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json
+```
+
+### ⚠️ ***Important: Two Different JSONs***
+
+- The file from:
+```bash
+gcloud auth application-default login
+```
+is your ***Application Default Credentials (ADC)*** — used by Terraform and `gcloud`.
+It is ***not*** the same as the Desktop OAuth client JSON.
+The Gmail MCP server requires the ***Desktop OAuth client JSON*** you downloaded.
+→ Place it at `~/.gmail-mcp/credentials.json`.
+
+### 🚀 ***When You Run the MCP Server***
+The server will open a browser window asking you to sign in and approve access.
+You'll see your app name (`Gmail MCP Local`) and the Gmail modify scope.
+After approving, tokens are cached locally (usually `~/.gmail-mcp/token.json`), so you won't need to approve again.
+
+
+---
+
+### ⚙️ **Install Required Tools**
+
+Before testing or running the Gmail MCP server, make sure the following tools are installed:
+
+#### 🟣 1. Install `uv`
+`uv` is a fast Python package manager used to run the Gmail MCP server.
+
+Check if it's already installed:
+```bash
+uv --version
+```
+If not, install it:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Verify:
+```
+uv --version
+```
+#### 🟠 2. Install Node.js (includes `npm` and `npx`)
+npx is used to run the MCP Inspector, which lets you test your Gmail MCP server locally.
+```bash
+brew install node
+```
+
+### 🧪 ***Testing Locally with MCP Inspector***
+Once toBefore connecting to Claude Desktop or a LangGraph agent, you can visually inspect and test your Gmail MCP server using the ***MCP Inspector*** web UI.
+
+#### 1️⃣ **Run with simple path (direct server entry)**
+Use this if you're already inside the ``gmail-mcp directory or the script path resolves cleanly:
+```bash
+npx @modelcontextprotocol/inspector uv run /Users/sebastianwefers/Desktop/development/recruitment-agent-mcp-hackathon-winter25/src/mcp_servers/gmail-mcp/src/gmail/server.py \
+  --creds-file-path ~/.gmail-mcp/credentials.json \
+  --token-path ~/.gmail-mcp/token.json
+```
+
+#### 2️⃣ **Run with full project context (recommended)**
+This variant is more robust and works regardless of your working directory, because it explicitly tells `uv` which project directory to use and where your binaries are.
+
+```bash
+npx @modelcontextprotocol/inspector \
+  /Users/sebastianwefers/.local/bin/uv \
+  --directory /Users/sebastianwefers/Desktop/development/recruitment-agent-mcp-hackathon-winter25/src/mcp_servers/gmail-mcp \
+  run gmail \
+  --creds-file-path ~/.gmail-mcp/credentials.json \
+  --token-path ~/.gmail-mcp/token.json
+```
+
+#### 🔍 What Happens
+When you run either command, you should see output similar to:
+```bash
+Starting MCP inspector...
+⚙️ Proxy server listening on localhost:6277
+🔑 Session token: 8498939effc01e03c1b879efa72768e45608056ef1ad45e5c80344a7d9362a72
+   Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth
+
+🚀 MCP Inspector is up and running at:
+   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=8498939effc01e03c1b879efa72768e45608056ef1ad45e5c80344a7d9362a72
+
+🌐 Opening browser...
+
+```
+
+This automatically opens a local browser window to the MCP Inspector UI, connected to your Gmail MCP server.
+
+✅ Expected behavior:
+- On first run, a browser window will prompt you to log in and approve access.
+- After successful OAuth, a token file will be created:
+```bash
+~/.gmail-mcp/token.json
+```
+- Subsequent runs reuse this token — no re-auth required.
+- You can now explore, invoke, and inspect your Gmail MCP tools visually (e.g., `listEmails`, `sendEmail`, `modifyLabel`, etc.) right from the web UI.
+
+### 💻 ***Connecting the Gmail MCP Server to Claude Desktop***
+1. Open your Claude Desktop configuration file:
+```bash
+nano ~/Library/Application Support/Claude/claude_desktop_config.json
+```
+2. Add this block (update paths if necessary):
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/Users/sebastianwefers/Desktop/development/recruitment-agent-mcp-hackathon-winter25/src/mcp_servers/gmail-mcp",
+        "run",
+        "gmail",
+        "--creds-file-path",
+        "/Users/sebastianwefers/.gmail-mcp/credentials.json",
+        "--token-path",
+        "/Users/sebastianwefers/.gmail-mcp/token.json"
+      ]
+    }
+  }
+}
+```
+3. Save the file and restart Claude Desktop.
+
+4. Open ***Settings → Model Context Protocol → Add Server***, then connect to gmail.
+
+Claude will now be able to:
+- 📥 Read emails
+- ✉️ Compose drafts
+- 🏷 Send and modify Gmail messages directly from your account.
+
+— all directly via your Gmail MCP server.
+
+
+## 🧩 Why Deleting token.json Fixes the “invalid_grant” Error
+The error occurs because the stored refresh token in token.json is expired or revoked, so Google rejects all refresh attempts.
+Deleting the file forces the app to start a new OAuth flow, prompting you to log in again and generating a new, valid refresh token — which restores access to the Gmail API.
+
+```bash
+# 1. Remove the invalid cached token
+rm /Users/sebastianwefers/Desktop/projects/recruitment-agent-mcp-hackathon-winter25/secrets/gmail-mcp/token.json
+
+
+# 2. Re-run the Gmail MCP server (which triggers OAuth again)
+python -m src.mcp_servers.gmail_mcp
+```
+
+Then, when the script printed a Google sign-in URL, you:
+1. Opened it in your browser,
+2. Logged in to your Google account,
+3. Approved the Gmail API access,
+4. And the new valid token.json was automatically recreated at:
+```bash
+~/.gmail-mcp/token.json
+```

docs/mcp/google_tools_mcp.md

@@ -0,0 +1,180 @@
+# Google Calendar and GMail Tools / MCP
+
+## 1) ***`Base setup`***
+### 1.1) ***GMail Account***
+
+### 1.2) ***Google Cloud***
+
+#### Terraform Modifications (Minimal)
+You can extend your existing Gmail Terraform to include Calendar support.
+Add these to your `main.tf`:
+```bash
+# Enable the Google Calendar API
+resource "google_project_service" "calendar_api" {
+  project = google_project.project.project_id
+  service = "calendar.googleapis.com"
+  disable_on_destroy = false
+}
+```
+And if you want, you can add an output for convenience:
+```bash
+output "console_calendar_api_url" {
+  value = "https://console.cloud.google.com/apis/library/calendar.googleapis.com?project=${google_project.project.project_id}"
+}
+```
+After adding, re-run your scripts:
+```bash
+cd terraform
+terraform apply
+```
+This enables the Calendar API in the same project your Gmail MCP is using — so you don't have to create a second one.
+
+Terraform will:
+1. Detect that you already have a project and Gmail API from before.
+2. Notice the new Calendar API resource in ``main.tf.
+3. Apply only that new change (plus any small diff in IAM roles if needed).
+
+💡 What Happens Internally
+When you run `terraform apply`, Terraform will:
+- Read your current state file (`terraform.tfstate`).
+- Query GCP to check what's already deployed.
+- Compute a plan (the difference between your state and the `.tf` files).
+
+#### 🔑 OAuth Setup — Shared Consent Screen
+You do not need a new consent screen — just reuse your existing one (Gmail MCP Local) and add the Calendar scope.
+
+Go to:
+👉 [Google Cloud Console → APIs & Services → OAuth consent screen → Edit app → Data access → Add scopes]
+Add this scope:
+```arduino
+https://www.googleapis.com/auth/calendar
+```
+You'll now have Gmail + Calendar under one consent.
+Then, create a ***second OAuth client***:
+Application type: Desktop app
+Name: `calendar-mcp-desktop`
+Download the credentials JSON → save it to:
+```bash
+~/.calendar-mcp/credentials.json
+```
+The Calendar MCP server will then use this credentials file when it first authenticates.
+
+#### 🧩  MCP Client Config (Claude or LangGraph)
+Just add a new block alongside your Gmail entry.
+For Claude Desktop (`claude_desktop_config.json`)
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/Users/sebastianwefers/Desktop/development/recruitment-agent-mcp-hackathon-winter25/src/mcp_servers/gmail-mcp",
+        "run",
+        "gmail",
+        "--creds-file-path",
+        "/Users/sebastianwefers/.gmail-mcp/credentials.json",
+        "--token-path",
+        "/Users/sebastianwefers/.gmail-mcp/token.json"
+      ]
+    },
+    "google_calendar": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/Users/sebastianwefers/Desktop/development/recruitment-agent-mcp-hackathon-winter25/src/mcp_servers/calendar-mcp",
+        "run",
+        "calendar"
+      ]
+    }
+  }
+}
+```
+
+For LangGraph:
+```python
+client = MultiServerMCPClient({
+    "gmail": {
+        "command": "uv",
+        "args": [
+            "--directory", "/Users/sebastianwefers/Desktop/development/recruitment-agent-mcp-hackathon-winter25/src/mcp_servers/gmail-mcp",
+            "run", "gmail",
+            "--creds-file-path", "/Users/sebastianwefers/.gmail-mcp/credentials.json",
+            "--token-path", "/Users/sebastianwefers/.gmail-mcp/token.json"
+        ],
+        "transport": "stdio"
+    },
+    "google_calendar": {
+        "command": "uv",
+        "args": [
+            "--directory", "/Users/sebastianwefers/Desktop/development/recruitment-agent-mcp-hackathon-winter25/src/mcp_servers/calendar-mcp",
+            "run", "calendar"
+        ],
+        "transport": "stdio"
+    }
+})
+```
+#### Environment Variables (.env)
+Create the .env in your calendar-mcp repo root, just like described in its README:
+```bash
+GOOGLE_CLIENT_ID='YOUR_CLIENT_ID'
+GOOGLE_CLIENT_SECRET='YOUR_CLIENT_SECRET'
+TOKEN_FILE_PATH='.gcp-saved-tokens.json'
+OAUTH_CALLBACK_PORT=8080
+CALENDAR_SCOPES='https://www.googleapis.com/auth/calendar'
+```
+⚠️ Make sure the redirect URI matches:
+```bash
+http://localhost:8080/oauth2callback
+```
+You'll go through one browser OAuth login on first run, and then `.gcp-saved-tokens.json` will be created — no need to repeat.
+
+
+## 2) ***`Model Context Protocol`***
+**References**
+- [Official MCP Docs](https://modelcontextprotocol.io/docs/getting-started/intro)
+- [MCP Crash Course by YouTuber & AI Engineer Dave Ebbelaar](https://www.youtube.com/watch?v=5xqFjh56AwM&t=761s)
+- *Existing Repo's*
+  - [Curated list of MCP servers](https://github.com/modelcontextprotocol/servers) hosted by `MCP` themselves.
+  - [Goole Calendar](https://github.com/deciduus/calendar-mcp/blob/main/README.md)
+  - calendar repo alterntives:
+    - https://github.com/nspady/google-calendar-mcp/tree/main/src/tools
+```psql
+# Calendar MCP (Dual Layer)
+LLM Agent
+   │
+   │  JSON-RPC over STDIO
+   ▼
+MCP Bridge (mcp_bridge.py)
+   │  HTTP requests to localhost:8000
+   ▼
+FastAPI Server (server.py)
+   │
+   └── Google Calendar API (OAuth + REST)
+```
+
+  - [GMail](https://github.com/theposch/gmail-mcp/blob/main/README.md)
+```psql
+    # Gmail MCP (Pure MCP)
+LLM Agent
+   │
+   │  JSON-RPC over STDIO
+   ▼
+Gmail MCP Server
+   │
+   └── Gmail API (OAuth + REST)
+```
+  - [Gmail](https://github.com/MCP-Mirror/Samarth2001_gmail-mcp)
+  - [Gmail](https://github.com/jasonsum/gmail-mcp-server)
+
+
+## 🧱 1️⃣ Compatibility Breakdown
+| Area                | Gmail MCP                                      | Calendar MCP                                    | Compatible? | Notes                                                                       |
+| ------------------- | ---------------------------------------------- | ----------------------------------------------- | ----------- | --------------------------------------------------------------------------- |
+| **Transport**       | MCP via STDIO                                  | MCP via STDIO (through FastAPI bridge)          | ✅           | Works out of the box with same client setup.                                |
+| **Auth Type**       | OAuth 2.0 Desktop Client                       | OAuth 2.0 Desktop Client                        | ✅           | Identical flow; can reuse same consent screen + test users.                 |
+| **Scopes**          | `https://www.googleapis.com/auth/gmail.modify` | `https://www.googleapis.com/auth/calendar`      | ✅           | Different scopes, but both can live under one consent screen.               |
+| **Terraform**       | Creates project, enables Gmail API, sets roles | Just needs Calendar API enabled too             | ✅           | Add one more API + scope to Terraform config.                               |
+| **Token Storage**   | `~/.gmail-mcp/token.json`                      | `.gcp-saved-tokens.json`                        | ✅           | Each uses its own token file; keep separate to avoid refresh token mix-ups. |
+| **Runtime**         | `uv` stdio server                              | `python run_server.py` (auto-switches to stdio) | ✅           | You can use `uv` for both, if you prefer consistency.                       |
+| **MCP Integration** | Claude / LangGraph via config                  | Same                                            | ✅           | Just add another entry under `mcpServers`.                                  |

intro.md

@@ -0,0 +1,457 @@
+# ***`Gradio Agents & MCP Hackathon Winter Edition 2025`***
+
+## 🏁 Overview
+This repository hosts our team's submission for **Track 2: MCP in Action** in the [MCP's 1st Birthday Hackathon](https://huggingface.co/MCP-1st-Birthday).
+
+Our goal is to build an **autonomous agentic system** that demonstrates:
+- **Planning, reasoning, and execution**
+- Integration of **custom tools, MCP tools, or external APIs**
+- Effective **context engineering**
+- Clear, practical **user value**
+
+We'll use **LangGraph** as our orchestration backbone for building multi-turn, tool-using, and context-aware agents.
+
+> ***`Check hackathon README for detilaed requirements.`***
+
+## 🧠 ***`Tools & Frameworks`***
+
+- 🧩 [LangGraph](https://docs.langchain.com/oss/python/langgraph/overview): for multi-agent orchestration and planning
+  - Why & how they built [LangGraph for production agents](https://blog.langchain.com/building-langgraph/)
+- 🧠 **LLM Engines:** [OpenAI](https://openai.com) / [Anthropic](https://www.anthropic.com) — reasoning and planning models
+  - gpt-oss inference providers
+    - [Open Router](https://openrouter.ai/openai/gpt-oss-20b):
+      - LangChain Wrapper: https://github.com/langchain-ai/langchain/discussions/27964
+    - [TogetherAI](https://www.together.ai/openai)
+- 💬 [Gradio](https://www.gradio.app/): for the UI and context-engineering demos
+- ⚙️ [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) Tools: standardized interfaces for Gmail, Google Calendar, Voice technologies and other APIs
+- ☁️ [Google Cloud Platform](https://cloud.google.com): optional backend for hosting MCP servers and integrated services
+- 📞 [Twilio](https://www.twilio.com/en-us): enables automated voice calls and candidate interactions
+- 🔊 [ElevenLabs](https://elevenlabs.io): (optional) natural text-to-speech for realistic voice screenings
+- 🎙️ [Whisper-based Transcription API](https://whisperapi.com) (or [OpenAI Whisper API](https://platform.openai.com/docs/guides/speech-to-text) ) — for speech-to-text functionality in voice interviews
+- 🧭 [Langfuse](https://langfuse.com) or [LangSmith](https://docs.langchain.com/langsmith/quick-start-studio): debugging, observability, and trace visualization
+- 📄 [Docling](https://www.docling.ai): for parsing and analyzing uploaded CV documents
+- 🧱 [Pydantic](https://docs.pydantic.dev/latest/): for structured outputs and data validation
+- 🔀 [Parlant](https://github.com/emcie-co/parlant): enables agents to handle multi-intent, free-form conversations by dynamically activating relevant guidelines instead of rigidly routing to a single sub-agent — solving the context fragmentation problem inherent in traditional LangGraph supervisor patterns.
+
+## 📚 ***`References for Context Engineering`***
+
+- [**Context Engineering for AI Agents — Manus Blog**](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus)
+- [**YouTube Talk Manus**](https://www.youtube.com/watch?v=6_BcCthVvb8&start=2525)
+- [**LangGraph Overview**](https://docs.langchain.com/oss/python/langgraph/overview)
+- https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
+- https://medium.com/fundamentals-of-artificial-intelligence/mitigate-context-poisoning-in-ai-agents-using-context-engineering-96cf40dbb38d
+- https://blog.langchain.com/context-engineering-for-agents/
+- **langgraph implementations**
+  - [video]((https://www.youtube.com/watch?v=nyKvyRrpbyY))
+  - [good notebooks](https://github.com/langchain-ai/how_to_fix_your_context/blob/main/notebooks/utils.py)
+- [Langgraph summary of what frontier labs and firms apply](https://www.youtube.com/watch?v=XFCkrYHHfpQ)
+
+These resources guide our approach to **memory management, planning transparency, and tool orchestration** in autonomous agents.
+
+## 🧾  ***`HR Candidate Screening Multi-Agent System`***
+An autonomous HR assistant that streamlines early recruitment through five steps:
+1. **CV Upload (Application)** — candidate applications uploaded and parsed
+2. **CV Screening** — rank and shortlist candidates using LLM reasoning
+3. **Voice Screening** — invite and coordinate interviews using a voice agent.
+4. **Person-to-Person Screening** — schedule HR interviews via Google Calendar integration
+5. **Decision** — generate a concise summary and notify HR
+
+> **`NOTE`**
+> - Final decision of whether candidate will be hired is made by human.
+> - Just automate the boring, tedious stuff while keeping human final decision in the loop.
+
+**Architecture:**
+1. **Main Planner Agent**: orchestrates the workflow
+2. **Subagents**:
+  - CV Screening Agent
+  - Voice Screening Agent
+  - Meeting Scheduler Agent
+3. **Tools (via MCP)** connect to Gmail, Calendar, and Voice APIs.
+4. **Database** stores both candidate info and persistent agent memory.
+5. **Gradio UI** visualizes workflow, reasoning, and results.
+```mermaid
+flowchart TD
+    subgraph MainAgent["🧠 Main Planner Agent"]
+        A1["Plans • Reasons • Executes"]
+    end
+
+    subgraph Subagents["🤖 Subagents"]
+        S1["📄 CV Screening"]
+        S2["🎙️ Voice Screening"]
+        S3["📅 Scheduling"]
+        S4["🧾 Decision Summary"]
+    end
+
+    subgraph Tools["⚙️ MCP & External Tools"]
+        T1["📧 Gmail"]
+        T2["🗓️ Google Calendar"]
+        T3["🗣️ Voice API"]
+    end
+
+    subgraph Data["🗄️ Database"]
+        D1["Candidate Data"]
+        D2["Context Memory (Cognitive Offloading)"]
+    end
+
+    subgraph UI["💬 Gradio Dashboard"]
+        U1["HR View & Interaction"]
+    end
+
+    %% Connections
+    MainAgent --> Subagents
+    Subagents --> Tools
+    Subagents --> Data
+    MainAgent --> Data
+    MainAgent --> UI
+```
+
+**GCP Setup for Judges:**
+A single demo Gmail/Calendar account (`scionhire.demo@gmail.com`) is pre-authorized via OAuth, with stored credentials in `.env`.
+Judges can run or view the live demo without any credential setup, experiencing real Gmail + Calendar automation safely.
+
+We use **hierarchical planning**:
+- **Main Agent:** decides next step in the workflow (plan, adapt, replan)
+- **Subagents:** specialized executors (screening, scheduling, summarization)
+- **Memory State:** tracks plan progress and tool results  
+- **Dashboard Visualization:** shows active plan steps and reasoning traces for transparency
+
+🧠 Why This Is an Agent (Not Just a Workflow)
+
+| Criterion | Workflow | Our System |
+|------------|-----------|-------------|
+| **Autonomy** | Executes fixed sequence of steps | Main agent decides next actions without manual triggers |
+| **Planning** | Predefined order (A → B → C) | Main agent generates and adapts a plan (e.g., skip, retry, re-order) |
+| **Reasoning** | No decision logic | Uses LLM reasoning to evaluate outputs and choose next subagent |
+| **Context Awareness** | Stateless | Maintains shared memory of candidates, progress, and outcomes |
+| **Adaptation** | Fails or stops on error | Re-plans (e.g., if calendar slots full or candidate unresponsive) |
+
+✅ **Therefore:** it qualifies as an *agentic system* because it **plans, reasons, and executes** autonomously rather than following a static workflow.
+
+## ***`Project Structure`***
+```
+agentic-hr/
+│
+├── 📁 src/
+│ │
+│ ├── 📁 core/
+│ │ │ ├── base_agent.py           # Abstract BaseAgent (LangGraph-compatible)
+│ │ │ ├── supervisor.py           # Supervisor agent (LangGraph graph assembly)
+│ │ │ ├── state.py                # Shared AgentState + context window
+│ │ │ ├── planner.py              # High-level planning logic
+│ │ │ └── executor.py             # Graph executor / runner
+│ │
+│ ├── 📁 agents/
+│ │ │
+│ │ ├── 📁 cv_screening/
+│ │ │ │ ├── agent.py              # CVScreeningAgent implementation
+│ │ │ │ ├── 📁 tools/
+│ │ │ │ │ ├── doc_parser.py
+│ │ │ │ │ ├── normalize_skills.py
+│ │ │ │ │ ├── rank_candidates.py
+│ │ │ │ │ └── match_to_jd.py
+│ │ │ │ └── 📁 schemas/
+│ │ │ │     ├── cv_schema.py      # Parsed CV Pydantic schema
+│ │ │ │     └── jd_schema.py      # Job description schema
+│ │ │
+│ │ ├── 📁 voice_screening/
+│ │ │ │ ├── agent.py              # VoiceScreeningAgent
+│ │ │ │ ├── 📁 tools/
+│ │ │ │ │ ├── twilio_client.py
+│ │ │ │ │ ├── whisper_transcribe.py
+│ │ │ │ │ └── tts_service.py
+│ │ │ │ └── 📁 schemas/
+│ │ │ │     ├── call_result.py
+│ │ │ │     └── transcript.py
+│ │ │
+│ │ ├── 📁 scheduler/
+│ │ │ │ ├── agent.py              # SchedulerAgent
+│ │ │ │ ├── 📁 tools/
+│ │ │ │ │ ├── calendar_tool.py
+│ │ │ │ │ ├── gmail_tool.py
+│ │ │ │ │ └── slot_optimizer.py
+│ │ │ │ └── 📁 schemas/
+│ │ │ │     └── meeting_schema.py
+│ │ │
+│ │ └── 📁 decision/
+│ │     ├── agent.py              # DecisionAgent (final summarizer/Reporter)
+│ │     └── 📁 schemas/
+│ │         └── decision_report.py
+│ │
+│ ├── 📁 mcp_server/
+│ │   ├── main.py
+│ │   ├── 📁 endpoints/
+│ │   ├── auth.py
+│ │   └── schemas.py
+│ │
+│ ├── 📁 gradio/
+│ │   ├── app.py                  # Main Gradio app (Hugging Face Space entry)
+│ │   ├── dashboard.py            # Live agent graph & logs view
+│ │   ├── candidate_portal.py     # Candidate upload / screening status
+│ │   ├── hr_portal.py            # HR review + interview approval
+│ │   ├── components.py           # Shared Gradio components
+│ │   └── 📁 assets/              # Logos, CSS, etc.
+│ │
+│ ├── 📁 cv_ui/
+│ │   ├── app.py 
+│ │
+��� ├── 📁 voice_screening_ui/
+│ │   ├── app.py 
+│ │
+│ │
+│ ├── 📁 prompts/
+│ │   ├── prompt_manager.py       # Centralized prompt versioning
+│ │   ├── cv_prompts.py
+│ │   ├── voice_prompts.py
+│ │   └── scheduler_prompts.py
+│ │
+│ ├── 📁 database/
+│ │   ├── models.py               # SQLAlchemy models
+│ │   ├── db_client.py            # Connection & CRUD
+│ │   └── context_sync.py         # Cognitive offloading (context ⇄ DB)
+│ │
+│ ├── main.py                     # CLI runner / local orchestrator entry
+│ └── config.py                   # Environment configuration
+│
+├── 📁 tests/
+│ │ ├── test_cv_agent.py
+│ │ ├── test_voice_agent.py
+│ │ ├── test_scheduler_agent.py
+│ │ ├── test_mcp_server.py
+│ │ └── test_integration.py
+│
+├── .env.example
+├── requirements.txt
+├── Dockerfile
+├── app.py                         # Shortcut to src/ui/app.py
+├── README.md
+└── LICENSE
+```
+
+## ***`Multi Agent System Architecture`***
+Below you will find an overview of the subagent components that mnake upo the entire system. More detailed information and brainstorming is decicated to the `docs/agents/..` directory.
+
+### 1) ***`Orchestrator`***
+#### Overview
+
+The orchestrator agent is reponsible for **supervising** and **triggering** the ***tasks of the subagents***.
+
+> For more planning and info, go to `docs/agents/agent_orchestrator.md`
+
+### 2) ***`CV Screener`***
+#### Overview
+The cv screening agent deals with scanning the applicant's CV's, and deciding who are fruitful versus unpromising candidates as a first filtering step.
+
+> For more planning and info, go to `docs/agents/cv_screening.md`
+
+### 3) 🎙️ ***`Voice Screening Agent`***
+
+#### Overview
+The **Voice Screening Agent** conducts automated phone interviews and integrates with the **LangGraph HR Orchestrator**.  
+It uses **Twilio** for phone calls, **Whisper/ASR** for speech-to-text, **ElevenLabs** for natural voice output, and **LangGraph** for dialogue logic.
+
+> For more planning and info, go to `docs/agents/voice_screening.md`
+
+### 4) ***`Google MCP Agents`***
+#### Overview
+The google mcp agents will be resposnible to:
+a) writing emails
+b) scheduling and menaging google calendar events
+
+It adviseable to break this up into two subagents, to get rid of `context poisoning`.
+
+> For more planning and info, go to `docs/agents/google_mcp_agent.md`
+
+### 4) ***`LLM as a Judge`***
+#### Overview
+LLM-as-a-judge will be leveraged to judge call screening results.
+
+> For more planning and info, go to `docs/agents/judging_agent.md`
+
+## 🗄️ ***`Data Layer`***
+
+The system uses a unified **SQLAlchemy-based database** for both **candidate data management** and **context engineering**.
+
+### 📦 Purpose
+| Data Type | Description |
+|------------|--------------|
+| 🧾 **Candidates** | Stores CVs, parsed data, and screening results |
+| 🎙️ **Voice Results** | Saves transcripts, evaluations, and tone analysis |
+| 🗓️ **Scheduling** | Tracks HR availability and confirmed interviews |
+| 🧠 **Agent Context Memory** | Enables **cognitive offloading** — storing reasoning traces and summaries so the active context stays uncluttered and information can be recalled when needed |
+| 📚 **Logs / Tool History** | Archives tool interactions and results for transparency and reuse |
+
+We use [**SQLAlchemy**](https://www.sqlalchemy.org) as the ORM layer to manage both structured candidate data and **persistent agent memory**, allowing the system to offload, summarize, and retrieve context efficiently across sessions.
+
+## 🗃️ ***`Prompt Archive`***
+
+To ensure consistent behavior and easy experimentation across subagents, the system includes a **centralized prompt management layer**.
+
+### 📦 Purpose
+| Component | Description |
+|------------|--------------|
+| 🧠 **Prompt Templates** | Stores standardized prompts for each subagent (CV screening, voice screening, scheduling) |
+| 🔄 **Prompt Versioning** | Allows tracking and updating of prompt iterations without changing agent code |
+| 🧩 **Dynamic Injection** | Enables context-dependent prompt construction using retrieved memory or database summaries |
+| 📚 **Archive** | Keeps older prompt variants for reproducibility and ablation testing |
+
+## 📺 ***`Gradio Interface`***
+
+We use **Gradio** to demonstrate our agent's reasoning, planning, and tool use interactively — fully aligned with the **Agents & MCP Hackathon** focus on **context engineering** and **user value**.
+
+### 🧩 Key Features
+| Section | Purpose |
+|----------|----------|
+| 🧍 **Candidate Portal** | Upload CVs, submit applications, and view screening results |
+| 🧑‍💼 **HR Portal** | Review shortlisted candidates, trigger voice screenings, and schedule interviews |
+| 🧠 **Agent Dashboard** | Visualizes the current plan, tool calls, and reasoning traces in real time |
+| ⚙️ **Tool Integration** | Shows live MCP actions (Gmail send, Calendar scheduling) with status updates |
+| 📊 **Context View** | Displays agent memory, current workflow stage, and adaptive plan updates |
+
+#### Context Engineering Visualization?
+This is what judges really care about — it must show that the system is agentic (reasoning, memory, planning).
+🧠 Agent Plan Viewer
+gr.JSON() or custom visual showing the current plan state, e.g.:
+```json
+{
+  "plan": [
+    "1. Screen CVs ✅",
+    "2. Invite for voice screening 🔄",
+    "3. Schedule HR interview ⬜",
+    "4. Await HR decision ⬜"
+  ]
+}
+```
+🗺️ Live Plan Progress
+- Use a progress bar or color-coded status list of steps.
+- Judges must see autonomous transitions (from one step to another).
+
+💬 Reasoning Log / Memory
+- Stream or text box showing LLM thought traces or context summary:
+  - “Detected strong match for Data Scientist role.”
+  - “Candidate completed voice interview; confidence: 8.4/10.”
+  - “Next step: scheduling HR interview.”
+
+⚙️ Tool Call Trace
+- Small table showing:
+
+| Time  | Tool     | Action           | Result    |
+| ----- | -------- | ---------------- | --------- |
+| 12:05 | Gmail    | `send_invite()`  | Sent      |
+| 12:06 | Calendar | `create_event()` | Confirmed |
+
+## 🔗 ***`MCP Integration (Best Practice Setup)`***
+
+To align fully with the **Agents & MCP Hackathon** standards, our system will use or extend a **standardized MCP server** for integrations such as **Gmail** and **Google Calendar** — and potentially **Scion Voice** in later stages.
+
+**`Inspired by`** [Huggingface MCP Course](https://huggingface.co/learn/mcp-course/en/unit2/introduction): shows how to build an MCP app.
+
+### 🧩 Why MCP?
+| Benefit | Description |
+|----------|--------------|
+| ✅ **Standardized** | Exposes Gmail & Calendar as reusable MCP tools with a consistent schema |
+| 🔐 **Secure** | OAuth handled once server-side — no tokens or secrets stored in the agent |
+| 🧱 **Modular** | Clean separation between the agent's reasoning logic and the integration layer |
+| 🔄 **Reusable** | Same MCP server can serve multiple projects or agents |
+| 🚀 **Hackathon-Ready** | Directly fulfills the “use MCP tools or external APIs” requirement |
+
+---
+
+### ⚙️ Why Use MCP Instead of Just Defining Tools
+| Approach | Limitation / Risk | MCP Advantage |
+|-----------|-------------------|----------------|
+| **Custom-defined tools** (e.g., direct Gmail API calls in code) | Each project must re-implement auth, rate limits, and API logic | MCP provides a *shared, pre-authorized* interface any agent can use |
+| **Embedded credentials** in `.env` | Security risk, harder for judges to test | Credentials handled server-side — no secrets in the repo |
+| **Tight coupling** between agent and tool | Hard to swap or extend integrations | MCP creates a plug-and-play API boundary between reasoning and execution |
+| **Limited reuse** | Tools only exist in one codebase | MCP servers can expose many tools to multiple agents dynamically |
+
+MCP turns these one-off integrations into **standardized, composable building blocks** that work across agents, organizations, or platforms — the same philosophy used by **Anthropic**, **LangChain**, and **Hugging Face** in 2025 agent ecosystems.
+
+
+We will build or extend the open-source [**mcp-gsuite**](https://github.com/MarkusPfundstein/mcp-gsuite) server and host it securely on **Google Cloud Run**.  
+This server manages authentication, token refresh, and rate limiting — while exposing standardized MCP actions like:
+```json
+{
+  "action": "gmail.send",
+  "parameters": { "to": "candidate@example.com", "subject": "Interview Invite", "body": "..." }
+}
+```
+
+and
+
+```json
+{
+  "action": "calendar.create_event",
+  "parameters": { "summary": "HR Interview", "start": "...", "end": "..." }
+}
+```
+This architecture lets our HR agent (and future projects) perform real email and scheduling actions via secure MCP endpoints — giving judges a safe, live demo of true agentic behavior with no local credential setup required.
+
+## 🧠 ***`Agent Supervisor — Why Parlant + LangGraph`***
+
+LangGraph provides a powerful orchestration backbone for planning, reasoning, and executing multi-agent workflows.  
+However, its common **supervisor pattern** has a key limitation: the supervisor routes each user query to **only one sub-agent** at a time.
+
+### ⚠️ Example Problem
+> “I uploaded my CV yesterday. Can I also reschedule my interview — and how long is the voice call?”
+
+A standard LangGraph supervisor would forward this entire message to, say, the **CV Screening Agent**,  
+missing the **scheduling** and **voice screening** parts — causing incomplete or fragmented responses.
+
+### 💡 Parlant as the Fix
+**[Parlant](https://github.com/emcie-co/parlant)** solves this by replacing single-route logic with **dynamic guideline activation**.  
+Instead of rigid routing, it loads multiple relevant *guidelines* into context simultaneously, allowing coherent handling of mixed intents.
+
+```python
+agent.create_guideline(
+  condition="User asks about rescheduling",
+  action="Call SchedulerAgent via LangGraph tool"
+)
+
+agent.create_guideline(
+  condition="User asks about voice screening duration",
+  action="Query VoiceScreeningAgent"
+)
+```
+
+If a user blends both topics, ***both guidelines trigger***, producing a unified, context-aware response.
+
+### ⚙️ Why Combine Them
+| Layer                         | Framework     | Role                                                                    |
+| ----------------------------- | ------------- | ----------------------------------------------------------------------- |
+| 🧠 **Workflow Orchestration** | **LangGraph** | Executes structured agent workflows (CV → Voice → Schedule → Decision). |
+| 💬 **Conversational Layer**   | **Parlant**   | Dynamically manages mixed intents using guideline-based reasoning.      |
+| 🔧 **Integration Layer**      | **MCP Tools** | Provides standardized access to Gmail, Calendar, and Voice APIs.        |
+
+
+Together, ***Parlant + LangGraph*** merge structured planning with conversational adaptability —
+enabling our HR agent to reason, plan, and respond naturally to complex, multi-topic interactions.
+
+## ✨ ***`Agentic Enhancements [BONUS]`***
+
+To make the system more **autonomous, interpretable, and resilient**, we integrated a few lightweight yet powerful improvements:
+
+- 🧠 **Self-Reflection** – before executing a step, the agent briefly states *why* it's taking that action, improving reasoning transparency.  
+- 🔄 **Adaptive Re-Planning** – if a subagent or tool call fails (e.g., no calendar slot, missing response, or API timeout), the main planner automatically updates its plan — skipping, retrying, or re-ordering steps instead of stopping.  
+- 🧮 **LLM Self-Evaluation** – after each stage (CV, voice, scheduling), a lightweight judge model rates the result and adds feedback for the next step.  
+- 🗂️ **Context Summary** – the dashboard displays a live summary of all candidates, their current stage, and key outcomes.  
+- 🤝 **Human-in-the-Loop Checkpoint** – HR receives a short confirmation prompt before final scheduling to ensure responsible autonomy.
+
+These enhancements demonstrate **true agentic behavior** — autonomous planning, adaptive execution, and transparent reasoning — in a simple, explainable way.
+
+## 👥 ***`Team`***
+| Member   |
+| -------- |
+| [Sebastian Wefers](https://github.com/Ocean-code-1995) |
+| [Owen Kaplinsky](https://github.com/owenkaplinsky) |
+| [SrikarMK](https://github.com/Srikarmk) |
+| [Dmitri Moscoglo](https://github.com/DimiM99) |
+
+# ***`License`***
+
+This project includes and builds upon [gmail-mcp](https://github.com/theposch/gmail-mcp),  
+which is licensed under the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html).
+
+This repository extends gmail-mcp for experimental integration and automation with Claude Desktop.  
+All modifications are distributed under the same GPLv3 license.
+
+> **Note:** The original gmail-mcp code has not been modified at this stage.

langgraph.json

@@ -0,0 +1,7 @@
+{
+    "dependencies": ["./src"],
+    "graphs": {
+        "supervisor": "src.agents.supervisor.supervisor_v2:supervisor_agent"
+    }
+}
+

package-lock.json

@@ -0,0 +1,6 @@
+{
+  "name": "recruitment-agent3",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {}
+}

requirements/agent.txt

@@ -0,0 +1,3 @@
+langchain
+langchain-openai
+langgraph

requirements/all.txt

@@ -0,0 +1,64 @@
+# Consolidated requirements with all dependencies
+# Deduplicated from all individual requirement files
+
+# Base dependencies
+python-dotenv
+pydantic>=2.0
+pydantic-settings
+promptlayer
+
+# LangChain & LangGraph
+langchain
+langchain-openai
+langchain-community
+langchain-mcp-adapters
+langgraph
+langgraph-cli
+
+# API Framework
+fastapi
+uvicorn[standard]
+
+# Web & HTTP
+websockets>=12.0
+requests
+aiohttp
+httpx>=0.28.1
+
+# Database
+sqlalchemy
+psycopg2-binary
+
+# Google APIs
+google-auth
+google-auth-oauthlib
+google-auth-httplib2
+google-api-python-client
+
+# MCP Server
+mcp
+
+# OpenAI
+openai
+
+# UI & Visualization
+streamlit
+rich
+
+# PDF & Image Processing
+pypdfium2
+pillow
+ftfy
+
+# Search & Tools
+duckduckgo-search
+langchain-tavily
+
+# Email validation
+email-validator
+pydantic[email]
+
+# Date utilities
+python-dateutil
+
+gradio==6.0.1

requirements/api.txt

@@ -0,0 +1,7 @@
+# API Layer dependencies
+-r base.txt
+
+fastapi
+uvicorn[standard]
+pydantic>=2.0
+

requirements/base.txt

@@ -0,0 +1,4 @@
+python-dotenv
+pydantic
+pydantic-settings
+promptlayer

requirements/cv_ui.txt

@@ -0,0 +1,15 @@
+# CV Upload UI requirements
+# Includes base requirements
+-r base.txt
+-r db.txt
+
+openai
+
+# Streamlit for UI
+streamlit
+
+# PDF processing
+pypdfium2
+pillow
+ftfy
+

requirements/db.txt

@@ -0,0 +1,4 @@
+# data base requirements
+-r base.txt
+sqlalchemy
+psycopg2-binary

requirements/mcp_calendar.txt

@@ -0,0 +1,15 @@
+# Google Calendar MCP Server requirements
+# Includes base requirements
+-r base.txt
+
+# MCP server framework
+mcp
+
+# Google Calendar API
+google-auth
+google-auth-oauthlib
+google-api-python-client
+
+# Date utilities
+python-dateutil
+

requirements/mcp_gmail.txt

@@ -0,0 +1,16 @@
+# Gmail MCP Server requirements
+# Includes base requirements
+-r base.txt
+
+# MCP server framework
+mcp
+
+# Gmail API
+google-auth
+google-auth-oauthlib
+google-api-python-client
+google-auth-httplib2
+
+# HTTP client
+httpx>=0.28.1
+

requirements/requirements.txt

@@ -0,0 +1,24 @@
+google-auth
+langgraph
+langchain
+langchain-openai
+langchain-mcp-adapters
+duckduckgo-search
+langchain-tavily
+langchain-community
+langgraph-cli
+promptlayer
+
+mcp
+pypdfium2
+pillow
+ftfy
+sqlalchemy
+psycopg2-binary
+pydantic
+pydantic-settings
+python-dotenv
+openai
+pypdfium2
+Pillow
+ftfy

requirements/supervisor.txt

@@ -0,0 +1,12 @@
+# Supervisor Agent requirements
+# Includes base requirements
+-r base.txt
+
+# LangGraph for agent orchestration
+langgraph
+langchain-community
+langchain-mcp-adapters
+streamlit
+rich
+requests
+

requirements/voice_proxy.txt

@@ -0,0 +1,10 @@
+-r base.txt
+-r db.txt
+fastapi
+uvicorn[standard]
+websockets>=12.0
+requests
+asyncio
+aiohttp
+email-validator
+pydantic[email]

requirements/voice_screening_ui.txt

@@ -0,0 +1,6 @@
+-r base.txt
+streamlit
+uvicorn[standard]
+requests
+
+

scripts/__init__.py

@@ -0,0 +1,2 @@
+"""CLI scripts package."""
+

scripts/db/__init__.py

@@ -0,0 +1,10 @@
+"""Database CLI utilities."""
+
+import sys
+import os
+
+# Add project root to sys.path for all db scripts
+project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '../../'))
+if project_root not in sys.path:
+    sys.path.insert(0, project_root)
+

scripts/db/debug_all.py

@@ -0,0 +1,60 @@
+"""
+Run all database debug checks.
+
+Run as follows:
+>>> POSTGRES_HOST=localhost POSTGRES_PORT=5433 POSTGRES_PASSWORD=password123 python -m scripts.db.debug_all
+
+This runs:
+1. Connection test
+2. Session query test
+3. List existing candidates
+"""
+
+import sys
+import os
+
+# Add project root to sys.path
+project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '../../'))
+if project_root not in sys.path:
+    sys.path.insert(0, project_root)
+
+from scripts.db.test_connection import test_connection
+from scripts.db.test_session import test_session_query
+from scripts.db.list_candidates import list_candidates
+
+
+def run_all_checks() -> None:
+    """Run all database diagnostic checks."""
+    print("=" * 50)
+    print("🔍 DATABASE DIAGNOSTICS")
+    print("=" * 50)
+    
+    # 1. Test connection
+    conn_ok = test_connection()
+    
+    if not conn_ok:
+        print("\n⛔ Stopping - connection failed")
+        return
+    
+    print()
+    
+    # 2. Test session
+    session_ok = test_session_query()
+    
+    if not session_ok:
+        print("\n⛔ Stopping - session failed")
+        return
+    
+    print()
+    
+    # 3. List candidates
+    list_candidates()
+    
+    print()
+    print("=" * 50)
+    print("✅ All checks completed")
+    print("=" * 50)
+
+
+if __name__ == "__main__":
+    run_all_checks()

scripts/db/list_candidates.py

@@ -0,0 +1,63 @@
+"""
+List candidates in the database.
+
+Run standalone:
+>>> POSTGRES_HOST=localhost POSTGRES_PORT=5433 python scripts/db/list_candidates.py
+"""
+
+from sqlalchemy.exc import ProgrammingError
+
+# Ensure project root is in path
+import scripts.db  # noqa: F401
+
+from src.database.candidates.client import SessionLocal
+from src.database.candidates.models import Candidate
+
+
+def list_candidates(limit: int = 10) -> bool:
+    """
+    Check and list existing candidates in the database.
+    
+    Args:
+        limit: Maximum number of candidates to display.
+    
+    Returns:
+        True if query successful, False otherwise.
+    """
+    print("--- 🧾 Checking Existing Candidates ---")
+    session = SessionLocal()
+    try:
+        count = session.query(Candidate).count()
+        print(f"📊 Found {count} candidate(s) in the database.")
+
+        if count == 0:
+            print("⚠️ No candidates found.")
+        else:
+            print(f"\n👀 Listing candidates (up to {limit}):")
+            candidates = (
+                session.query(Candidate)
+                .order_by(Candidate.full_name)
+                .limit(limit)
+                .all()
+            )
+            for c in candidates:
+                print(f" - {c.full_name} | {c.email} | Status: {c.status}")
+        
+        return True
+
+    except ProgrammingError as e:
+        print("❌ Table 'candidates' does not exist or schema not initialized.")
+        print("ℹ️ Try running your DB initialization script or migrations.")
+        print(f"Error: {e}")
+        return False
+    except Exception as e:
+        print("❌ Error during candidate check.")
+        print(f"Error: {e}")
+        return False
+    finally:
+        session.close()
+
+
+if __name__ == "__main__":
+    list_candidates()
+

scripts/db/test_connection.py

@@ -0,0 +1,51 @@
+"""
+Test basic database connection.
+
+Run standalone:
+>>> POSTGRES_HOST=localhost POSTGRES_PORT=5433 python scripts/db/test_connection.py
+"""
+
+import os
+from sqlalchemy import text
+
+# Ensure project root is in path
+import scripts.db  # noqa: F401
+
+from src.database.candidates.client import get_engine
+
+
+def test_connection() -> bool:
+    """
+    Test basic database connectivity.
+    
+    Returns:
+        True if connection successful, False otherwise.
+    """
+    print("--- Testing Database Connection ---")
+    
+    # Print environment info
+    print(f"POSTGRES_HOST (env): {os.environ.get('POSTGRES_HOST')}")
+    print(f"POSTGRES_PORT (env): {os.environ.get('POSTGRES_PORT')}")
+    
+    try:
+        engine = get_engine()
+        print(f"Engine URL: {engine.url}")
+        
+        with engine.connect() as connection:
+            print("✅ Connection successful!")
+            result = connection.execute(text("SELECT 1"))
+            print(f"✅ SELECT 1 result: {result.fetchone()}")
+            return True
+            
+    except Exception as e:
+        print("\n❌ Connection FAILED")
+        print(f"Error type: {type(e).__name__}")
+        print(f"Error message: {str(e)}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+
+if __name__ == "__main__":
+    test_connection()
+

scripts/db/test_session.py

@@ -0,0 +1,40 @@
+"""
+Test database session and query execution.
+
+Run standalone:
+>>> POSTGRES_HOST=localhost POSTGRES_PORT=5433 python scripts/db/test_session.py
+"""
+
+from sqlalchemy import text
+
+# Ensure project root is in path
+import scripts.db  # noqa: F401
+
+from src.database.candidates.client import SessionLocal
+
+
+def test_session_query() -> bool:
+    """
+    Test session creation and basic query execution.
+    
+    Returns:
+        True if session works, False otherwise.
+    """
+    print("--- Testing Session Query ---")
+    session = SessionLocal()
+    try:
+        result = session.execute(text("SELECT now()"))
+        print(f"✅ Session execute successful: {result.fetchone()[0]}")
+        return True
+        
+    except Exception as e:
+        print("\n❌ Session Query FAILED")
+        print(f"Error: {e}")
+        return False
+    finally:
+        session.close()
+
+
+if __name__ == "__main__":
+    test_session_query()
+